api.md

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 is available on our flagship instance.

NeoDB also supports a subset of Mastodon API, details can be found in Mastodon API documentation.

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"}