From a5699898c53e52c23f29db28e88efdef82f05fcf Mon Sep 17 00:00:00 2001 From: Pere Lev Date: Thu, 4 Jul 2024 19:45:10 +0300 Subject: [PATCH] Docs: Start API.md documentation file --- API.md | 176 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 4 +- vervis.cabal | 3 +- 3 files changed, 180 insertions(+), 3 deletions(-) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 0000000..e0e8241 --- /dev/null +++ b/API.md @@ -0,0 +1,176 @@ +This document describes the Client-to-Server API of Vervis. If you're +developing a frontend application, or a forge search engine, or anything else +that wants to interact with Vervis instances, and wondering what language +Vervis speaks, this is the document for you. + +I suppose in the future it should sit on a Docusaurus website or something like +that. For now it's here. + +# Public Browsing + +The `/browse` page lists the public actors and resource hosted on the server. +However there's currently no AP version of that page. + +# Server Information + +NodeInfo isn't implemented yet. + +# Registration and Authorization + +Creating an account on a Vervis instance allows to: + +1. Create and manipulate resources (such as projects, repositories, teams) +2. View non-public information + +## Register the application + +### Register client + +Send a POST request to the `/oauth/apps` endpoint: + +```sh +curl -X POST \ + -F 'client_name=Anvil' \ + -F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \ + -F 'scopes=read' \ + -F 'website=https://anvil.forgefed.org' \ + -F 'repository=https://codeberg.org/Anvil/Anvil' \ + https://vervis.example/oauth/apps +``` + +- `redirect_uris` currently supports specifying only one URI, and there are 2 + options: + - The special value `urn:ietf:wg:oauth:2.0:oob`, which means out-of-band: + In this case, Vervis will respond with an HTML page containing a token + that needs to be manually copied + - An HTTPS URI: In this case, Vervis will redirect to the given URI +- The only supported scope is currently `read`, and despite the misleading + name, it allows all API operations + +The response, upon success, is a JSON object with 2 text fields: + +- `client_id` +- `client_secret` + +Keep these stored for future use. + +### Obtain an Application Access Token + +Send a POST request to the `/oauth/token` endpoint: + +```sh +curl -X POST \ + -F 'client_id=your_client_id_here' \ + -F 'client_secret=your_client_secret_here' \ + -F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \ + -F 'grant_type=client_credentials' \ + https://vervis.example/oauth/token +``` + +- `redirect_uri` must be the one defined when registering the application + +The response is a JSON object with: + +- `access_token`: Text, keep for later use +- `token_type`: Text, always "Bearer" +- `scope`: Text, always "read" +- `created_at`: Integer, time as POSIX seconds + +### Verify the Application Access Token + +You can verify the token works by sending a GET request to the +`/oauth/verify_credentials` endpoint: + +```sh +curl \ + -H 'Authorization: Bearer our_access_token_here' \ + https://vervis.example/oauth/verify_credentials +``` + +## Register an Account + +There's currently no API endpoint for creating a new account. + +## Log in as Existing User + +### Obtain authorization code + +In a browser, send a GET request to the `/oauth/authorize` endpoint: + +``` +https://vervis.example/oauth/authorize +?client_id=CLIENT_ID +&scope=read +&redirect_uri=urn:ietf:wg:oauth:2.0:oob +&response_type=code +``` + +- If `redirect_uri` is the special one as in the example above, the response + will be an HTML page containing the authorization code. +- Otherwise, Vervis will redirect to the `redirect_uri`, specifying the + authorization code as a query parameter named "code": + +`redirect_uri?code=qDFUEaYrRK5c-HNmTCJbAzazwLRInJ7VHFat0wcMgCU` + +### Obtain a User Access Token + +Now that we have the code, send a POST request to the `/oauth/token` endpoint +(which we previously used when registering the application): + +```sh +curl -X POST \ + -F 'client_id=your_client_id_here' \ + -F 'client_secret=your_client_secret_here' \ + -F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \ + -F 'grant_type=authorization_code' \ + -F 'code=user_authzcode_here' \ + -F 'scope=read' \ + https://vervis.example/oauth/token +``` + +The response is a JSON object with: + +- `access_token`: Text, keep for later use +- `token_type`: Text, always "Bearer" +- `scope`: Text, always "read" +- `created_at`: Integer, time as POSIX seconds + +### Verify the User Access Token & Obtain Actor Object + +You can verify the token works by sending a GET request to the +`/oauth/verify_credentials` endpoint: + +```sh +curl \ + -H 'Authorization: Bearer our_access_token_here' \ + https://vervis.example/oauth/verify_credentials +``` + +The response is a JSON object that has a `url` field, whose value is the HTTPS +URI of the user's `Person` ActivityPub JSON object. + +### Perform Authorized Requests + +You can now use the access token via the `Authorization` header, as in the curl +example above. + +- For GET requests, it allows to obtain non-public data +- For POST requests, it allows to publish ActivityPub activities via the user + outbox + +# Getting ActivityPub objects + +You can obtain an ActivityPub object by sending GET request to its `id` URI, +with `Content-Type` being +`application/ld+json; profile="https://www.w3.org/ns/activitystreams`. Unless +you've been given such a URI, the starting points for discovering objects are: + +- Public browsing page (which doesn't yet have an AP representation) +- The user `Person` object, whose URI can be obtained from + `/oauth/verify_credentials` as described above + +# Publishing and Manipulating Objects + +All object manipulation in Vervis is done using the ActivityPub C2S API, i.e. +by POSTing `Activity` objects to the user's `outbox`. A list of supported +activities will soon be added here and/or in the ForgeFed specification. diff --git a/README.md b/README.md index ce14ca0..7b9c280 100644 --- a/README.md +++ b/README.md @@ -210,9 +210,9 @@ about some bug or missing feature causing loss of data or access. [ ] Clear policy and guidelines for DB schema changes [ ] Running instance has data backups -## Federation +## Federation & API -See `FEDERATION.md`. +See `FEDERATION.md` & `API.md`. ## Installation diff --git a/vervis.cabal b/vervis.cabal index 7d24133..b65a3c5 100644 --- a/vervis.cabal +++ b/vervis.cabal @@ -18,7 +18,8 @@ maintainer: pere@towards.vision copyright: ♡ Copying is an act of love. Please copy, reuse and share. category: Development, Distribution, Git, Web build-type: Simple -extra-source-files: AUTHORS.md +extra-source-files: API.md + AUTHORS.md CHANGELOG.md COPYING FEDERATION.md