Docs: Start API.md documentation file

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.

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
 

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