81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
# API
|
|
|
|
## Endpoints
|
|
|
|
NeoDB has a set of API endpoints mapping to its functions like marking a book or listing collections, they can be found in swagger based API documentation at `/developer/` of your running instance, [a version of it](https://neodb.social/developer/) is available on our flagship instance.
|
|
|
|
NeoDB also supports a subset of Mastodon API, details can be found in [Mastodon API documentation](https://docs.joinmastodon.org/api/).
|
|
|
|
Both set of APIs can be accessed by the same access token.
|
|
|
|
## How to authorize
|
|
|
|
### Create an application
|
|
|
|
you must have at least one URL included in the Redirect URIs field, e.g. `https://example.org/callback`, or use `urn:ietf:wg:oauth:2.0:oob` if you don't have a callback URL.
|
|
|
|
```
|
|
curl https://neodb.social/api/v1/apps \
|
|
-d client_name=MyApp \
|
|
-d redirect_uris=https://example.org/callback \
|
|
-d website=https://my.site
|
|
```
|
|
|
|
and save of the `client_id` and `client_secret` returned in the response:
|
|
|
|
```
|
|
{
|
|
"client_id": "CLIENT_ID",
|
|
"client_secret": "CLIENT_SECRET",
|
|
"name": "MyApp",
|
|
"redirect_uri": "https://example.org/callback",
|
|
"vapid_key": "PUSH_KEY",
|
|
"website": "https://my.site"
|
|
}
|
|
```
|
|
|
|
|
|
### Guide your user to open this URL
|
|
|
|
```
|
|
https://neodb.social/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://example.org/callback&scope=read+write
|
|
```
|
|
|
|
### Once authorizated by user, it will redirect to `https://example.org/callback` with a `code` parameter:
|
|
|
|
```
|
|
https://example.org/callback?code=AUTH_CODE
|
|
```
|
|
|
|
### Obtain access token with the following POST request:
|
|
|
|
```
|
|
curl https://neodb.social/oauth/token \
|
|
-d "client_id=CLIENT_ID" \
|
|
-d "client_secret=CLIENT_SECRET" \
|
|
-d "code=AUTH_CODE" \
|
|
-d "redirect_uri=https://example.org/callback" \
|
|
-d "grant_type=authorization_code"
|
|
```
|
|
|
|
and access token will be returned in the response:
|
|
|
|
```
|
|
{
|
|
"access_token": "ACCESS_TOKEN",
|
|
"token_type": "Bearer",
|
|
"scope": "read write"
|
|
}
|
|
```
|
|
|
|
### Use the access token to access protected endpoints like `/api/me`
|
|
|
|
```
|
|
curl -H "Authorization: Bearer ACCESS_TOKEN" -X GET https://neodb.social/api/me
|
|
```
|
|
|
|
and response will be returned accordingly:
|
|
|
|
```
|
|
{"url": "https://neodb.social/users/xxx/", "external_acct": "xxx@yyy.zzz", "display_name": "XYZ", "avatar": "https://yyy.zzz/xxx.gif"}
|
|
```
|