From 6ff160b9c674e4a35e0213ba48a015cd60c6c767 Mon Sep 17 00:00:00 2001 From: rr- Date: Sat, 9 Apr 2016 08:59:40 +0200 Subject: [PATCH] docs/api: add documentation --- API.md | 275 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 00000000..74de9cc8 --- /dev/null +++ b/API.md @@ -0,0 +1,275 @@ +`szurubooru` uses REST API for all operations. + + + +## Table of contents + +1. [General rules](#general-rules) + + - [Authentication](#authentication) + - [Basic requests](#basic-requests) + - [File uploads](#file-uploads) + - [Error handling](#error-handling) + +2. [API reference](#api-reference) + + - [Listing users](#listing-users) + - [Creating user](#creating-user) + - [Updating user](#updating-user) + - [Getting user](#getting-user) + - [Password reset - step 1: mail request](#password-reset---step-2-confirmation) + - [Password reset - step 2: confirmation](#password-reset---step-2-confirmation) + +3. [Resources](#resources) + + - [User](#user) + +4. [Search](#search) + + + +## General rules + +### Authentication + +Authentication is achieved by means of [basic HTTP +auth](https://en.wikipedia.org/wiki/Basic_access_authentication). For this +reason, it is recommended to connect through HTTPS. There are no sessions, so +every privileged request must be authenticated. Available privileges depend on +the user's rank. The way how rank translates to privileges is defined in the +server's configuration. + +It is recommended to add `?bump-login` GET parameter to the first request in a +client "session" (where the definition of a session is up to the client), so +that the user's last login time is kept up to date. + +### Basic requests + +Every request must use `Content-Type: application/json` and `Accept: +application/json`. An exception to this rule are requests that upload files. + +### File uploads + +Requests that upload files must use `multipart/form-data` encoding. JSON +metadata must then be included as field of name `metadata`, whereas files must +be included as separate fields with names specific to each request type. + +### Error handling + +All errors (except for unhandled fatal server errors) send relevant HTTP status +code together with JSON of following structure: + +```json5 +{ + "title": "Generic title of error message, e.g. 'Not found'", + "description": "Detailed description of what went wrong, e.g. 'User `rr-` not found." +} +``` + + + +## API reference + +Depending on the deployment, the URLs might be relative to some base path such +as `/api/`. Values denoted in diamond braces (``) signify variable +data. + + +### Listing users +Request: `GET /users/?page=&query=` +Output: +```json5 +{ + "query": "rr-", + "users": [ + , + , + , + , + + ], + "page": 1, + "pageSize": 5, + "total": 7 +} +``` +...where `` is an [user resource](#user) and `query` contains standard +[search query](#search). + +Searches for users. + +Available search named tokens: + +| name | ranged? | array? | +| ----------------- | ------- | ------ | +| (anonymous) | | ✓ | +| `name` | | ✓ | +| `creation-date` | ✓ | ✓ | +| `creation-time` | ✓ | ✓ | +| `last-login-date` | ✓ | ✓ | +| `last-login-time` | ✓ | ✓ | +| `login-date` | ✓ | ✓ | +| `login-time` | ✓ | ✓ | + +Anonymous search tokens are equivalent to `name` token. + +Available search orders: + +- `random` +- `name` +- `creation-date` +- `creation-time` +- `last-login-date` +- `last-login-time` +- `login-date` +- `login-time` + + +### Creating user +Request: `POST /users` +Input: +```json5 +{ + "name": , + "password": , + "email": +} +``` +Output: +```json5 +{ + "user": +} +``` +...where `` is an [user resource](#user). +Errors: if such user already exists (names are case insensitive), or either of +user name, password and email are invalid. + +Creates a new user using specified parameters. Names and passwords must match +`user_name_regex` and `password_regex` from server's configuration, +respectively. Email address is optional. If the user happens to be the first +user ever created, they're granted highest available rank, becoming an +administrator. Subsequent users will be given the rank indicated by +`default_rank` in the server's configuration. + + +### Updating user +Request: `PUT /user/` +Input: +```json5 +{ + "name": , + "password": , + "email": , + "rank": +} +``` +Output: +```json5 +{ + "user": +} +``` +...where `` is an [user resource](#user). +Errors: if the user does not exist, or the user with new name already exists +(names are case insensitive), or either of user name, password, email or rank +are invalid, or the user is trying to update their or someone else's rank to +higher than their own. + +Updates an existing user using specified parameters. Names and passwords must +match `user_name_regex` and `password_regex` from server's configuration, +respectively. All fields are optional - update concerns only provided fields. +To update last login time, see [authentication](#authentication). + + +### Getting user +Request: `GET /user/` +Output: +```json5 +{ + "user": +} +``` +...where `` is an [user resource](#user). +Errors: if the user does not exist. + +Retrieves information about an existing user. + + +### Password reset - step 1: mail request +Request: `GET /password-reset/` +Output: +``` +{} +```` +Errors: if the user does not exist, or they haven't provided an email address. + +Sends a confirmation email to given user. The email contains link containing a +token. The token cannot be guessed, thus using such link proves that the person +who requested to reset the password, also owns the mailbox, which is a strong +indication they are the rightful owner of the account. + + +### Password reset - step 2: confirmation +Request: `POST /password-reset/` +Input: +```json5 +{ + "token": +} +``` +Output: +```json5 +{ + "password": +} +``` +Errors: if the token is missing, the token is invalid or the user does not +exist. + +Generates a new password for given user. Password is sent as plain-text, so it +is recommended to connect through HTTPS. + + + +## Resources + +### User + +```json5 +{ + "id": 2, + "name": "rr-", + "email": "rr-@sakuya.pl", // available only if the request is authenticated by the same user + "rank": "admin", // controlled by server's configuration + "rankName": "Administrator", // controlled by server's configuration + "lastLoginTime": "2016-04-08T20:20:16.570517", + "creationTime": "2016-03-28T13:37:01.755461", + "avatarStyle": "gravatar", // "gravatar" or "manual" + "avatarUrl": "http://gravatar.com/(...)" +} +``` + +## Search + +Nomenclature: + +- Tokens - search terms inside a query, separated by white space. +- Anonymous tokens - tokens of form `value`, used to filter the search results. +- Named tokens - tokens of form `key:value`, used to filter the search results. +- Special tokens - tokens of form `special:value`, used to filter the search results. +- Order tokens - tokens of form `order:value`, used to sort the search results. + +Features: + +- Most of tokens can be negated like so: `-token`. For order token it flips the + sort direction. +- Some tokens support multiple values like so: `3,4,5`. +- Some tokens support ranges like so: `100..`, `..200`, `100..200`. +- Date token values can contain following values: `today`, `yesterday`, + ``, `-`, `--`. +- Order token values can be suffixed with `,asc` or `,desc`. + +Example how it works: + + haruhi -kyon fav-count:3.. order:fav-count,desc -special:liked