Docs: Start API.md documentation file
This commit is contained in:
Pere Lev
parent
26ace5f9b8
commit
a5699898c5
3 changed files with 180 additions and 3 deletions
176
API.md
Normal file
176
API.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue