gallery.accords-library.com/API.md

szurubooru uses REST API for all operations.

Table of contents

1. General rules

   • Authentication
   • Basic requests
   • File uploads
   • Error handling

2. API reference

   • Listing users
   • Creating user
   • Updating user
   • Getting user
   • Removing user
   • Password reset - step 1: mail request
   • Password reset - step 2: confirmation

3. Resources

   • User

4. Search

General rules

Authentication

Authentication is achieved by means of basic HTTP auth. 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:

{
    "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 with diamond braces (<like this>) signify variable data.

Listing users

Request

GET /users/?page=<page>&pageSize=<page-size>&query=<query>

Output

{
    "query": "rr-",
    "users": [
        <user>,
        <user>,
        <user>,
        <user>,
        <user>
    ],
    "page": 1,
    "pageSize": 5,
    "total": 7
}

...where <user> is an user resource and query contains standard search query.

Errors

• privileges are too low

Description

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

{
    "name": <user-name>,
    "password": <user-password>,
    "email": <email>
}

Output

{
    "user": <user>
}

...where <user> is an user resource.

Errors

• such user already exists (names are case insensitive)
• either user name, password or email are invalid
• privileges are too low

Description

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/<name>

Input

{
    "name": <user-name>,
    "password": <user-password>,
    "email": <email>,
    "rank": <rank>,
    "avatarStyle": <avatar-style>
}

Files

• avatar - the content of the new avatar.

Output

{
    "user": <user>
}

...where <user> is an user resource.

Errors

• the user does not exist
• the user with new name already exists (names are case insensitive)
• either user name, password, email or rank are invalid
• the user is trying to update their or someone else's rank to higher than their own
• privileges are too low
• avatar is missing for manual avatar style

Description

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. Avatar style can be either gravatar or manual. manual avatar style requires client to pass also avatar file - see file uploads for details.

Getting user

Request

GET /user/<name>

Output

{
    "user": <user>
}

...where <user> is an user resource.

Errors

• the user does not exist
• privileges are too low

Description

Retrieves information about an existing user.

Removing user

Request

DELETE /user/<name>

Output

{}

Errors

• the user does not exist
• privileges are too low

Description

Deletes existing user.

Password reset - step 1: mail request

Request

GET /password-reset/<email-or-name>

Output

{}

Errors

• the user does not exist
• the user hasn't provided an email address

Description

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/<email-or-name>

Input

{
    "token": <token-from-email>
}

Output

{
    "password": <new-password>
}

Errors

• the token is missing
• the token is invalid
• the user does not exist

Description

Generates a new password for given user. Password is sent as plain-text, so it is recommended to connect through HTTPS.

Resources

User

{
    "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 tokens can be negated like so: -token. Used with order tokens, 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, <year>, <year>-<month>, <year>-<month>-<day>.
• Order token values can be appended with ,asc and ,desc suffixes, which control the sort direction.

Example how it works:

haruhi -kyon fav-count:3.. order:fav-count,desc -special:liked