https://api.example.com

Blueprint Docs

This API blueprint is subject to change due to technology restrictions, performance optimizations or changing requirements.

Authentication

  • This API uses JWT for authentication,

  • Every token MUST be refreshed before its expiration time,

  • Token MUST be provided in Authorization header,

  • Toke MUST be provided for each request that requires authentication,

  • This API issues a long-lived access tokens for consumers. A long-lived JWT generally SHOULD lasts about 30 days. If no requests are made, the token MUST expire and the user MUST go through the login flow again to get a new one.

A custom scheme like "JWT" seems to be more appropriate than coercing the OAuth2 Bearer scheme.

Example Header

Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhNnZoQW8zRkc3dDEiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE0NzA1OTg5NzIsImV4cCI6MTQ3MDY4NTM3Mn0.ltA9zZmJKszBJuuV7pTWtY7LzLXrRUfebJDhy_jGMeM

Claims

  • exp - The exp ( expiration time ) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.

  • iat - The iat ( issued at ) claim identifies the time at which the JWT was issued.

  • sub - The aud ( audience ) claim identifies the subject of this token (for e.g. a user id).

  • iss - The iss ( issuer ) claim identifies the principal that issued the JWT.

Consumer Identification

This API uses User-Agent and Application-Id headers to identify API consumer. Application-Id MUST contain an UUID that uniquely identifies a particular consumer installation.

Example Headers

User-Agent: Mozilla/5.0 (Linux; Android 4.4; Nexus 5 Build/_BuildID_) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/30.0.0.0 Mobile Safari/537.36
Application-Id: 6454d937-0a18-44a8-b482-bb48684f1ed4

Filtering, Ordering, Pagination & Searching

Filtering

This API can filter returned collections based on provided query parameters. Virtually any model field can be used as a filter.

For example, when requesting a list of movies from the /movies endpoint, you may want to limit these to only those of drama genre. This could be accomplished with a request like GET /movies?genre=drama. Here, genre is a query parameter that implements a filter.

Ordering

This API can sort returned collections. A generic query parameter sort is used to describe sorting rules. This parameter can take a list of comma separated field, each with a possible unary negative to imply descending sort order.

E.g. GET /movies?sort=-rating - Retrieves a list of movies in descending order of user rating.

By default all resources are ordered by their creation time, from newest to oldest.

Pagination

This API uses the Link header - RFC 5988 to include pagination details.

An example of a Link header is described in GitHub documentation.

This API returns total count of paged resources in Total-Count HTTP header.

Searching

This API uses a generic parameter search to expose a full text search mechanism.

HTTP Methods

This API uses HTTP verbs (methods) as following:

  • GET - Read - used to read (or retrieve) a representation of a resource,

  • POST - Create - used to create new resources. In particular, it's used to create subordinate resources.

  • PUT - Update/Replace - used for update capabilities, PUT-ing to a known resource URI with the request body containing the newly-updated representation of the original resource. On successful request, replaces identified resource with the request body.

  • PATCH - Update/Modify - used for modify capabilities. The PATCH request only needs to contain the changes to the resource, not the complete resource.

  • DELETE - Delete - used to delete a resource identified by a URI.

Localization

This API uses Accept-Language header to identify the locale.

Accept-Language: en

This header SHOULD be present in every request. If not, API MUST use the english language/locale.

Media Type

Where applicable this API MUST use the JSON media-type. Requests with a message-body are using plain JSON to set or update resource states.

Content-type: application/json and Accept: application/json headers SHOULD be set on all requests if not stated otherwise.

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Representation of Date and Time

All exchange of date and time-related data MUST be done according to ISO 8601 standard and stored in UTC.

When returning date and time-related data YYYY-MM-DDThh:mm:ss.SSSZ format MUST be used.

Resource IDs

This API uses short non-sequential url-friendly unique ids. Every resource id MUST consists of 9 url-friendly characters: A-Z, a-z, 0-9, _ and -.

Example

a6vhAo3FG7t1

Status Codes and Errors

This API uses HTTP status codes to communicate with the API consumer.

  • 200 OK - Response to a successful GET, PUT, PATCH or DELETE.

  • 201 Created - Response to a POST that results in a creation.

  • 204 No Content - Response to a successful request that won't be returning a body (like a DELETE request).

  • 400 Bad Request - Malformed request; form validation errors.

  • 401 Unauthorized - When no or invalid authentication details are provided.

  • 403 Forbidden - When authentication succeeded but authenticated user doesn't have access to the resource.

  • 404 Not Found - When a non-existent resource is requested.

  • 405 Method Not Allowed - Method not allowed.

  • 406 Not Acceptable - Could not satisfy the request Accept header.

  • 415 Unsupported Media Type - Unsupported media type in request.

Error response

This API returns both, machine-readable error codes and human-readable error messages in response body when an error is encountered.

Example

Validation Error
{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Invalid query parameters",
    "data": {
        "code": 10003,
        "validation": {
            "details":[
                {
                    "message": "\"name\" is required",
                    "path": "name",
                    "type": "any.required",
                    "context": {
                        "key": "name"
                    }
                },{
                    "message": "\"email\" must be a valid email",
                    "path": "email",
                    "type": "string.email",
                    "context": {
                        "value": "foo",
                        "key": "email"
                    }
                }
            ],
            "source": "query",
            "keys": [ "name","email" ]
        }
    }
}
Generic Error
{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "Your account is suspended and is not permitted to access this feature",
    "data": {
        "code": 13003
    }
}

Error Codes Dictionary

  • 10003 - Invalid query parameters

  • 10005 - Date is not in ISO 8601 standard

  • 10010 - Invalid Content-Type

  • 10011 - Invalid User-Agent

  • 10012 - Invalid or missing Application-Id

  • 11001 - Invalid or expired token

  • 11003 - Bad authentication data - Method requires authentication but it was not presented or was wholly invalid.

  • 11005 - Account not allowed to access this endpoint

  • 13003 - Your account is suspended and is not permitted to access this feature

Versioning

This API uses Api-Version header to identify requested version. Every minor version SHOULD be backward compatible. However, major versions MAY introduce breaking changes.

Api-Version: 1.0.0

This header SHOULD be present in every request. If not, API MUST use the newest available major release.

If requested version is not available, API SHOULD try to fall back to the next available minor release.

Authentication

User login

Access tokens are required to access nearly all endpoints of this API.

POST /auth/login Retrieve a token

Allows to retrieve a valid JSON Web Token for username and password.

Endpoint information
Requires authentication No
Has restricted scope No

Example URI

POST https://api.example.com/auth/login

Headers

Content-Type: application/json

Body

{
  "login": "john.doe@mail.com",
  "password": "QXR0mi38a2"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "login": {
      "type": "string",
      "description": "User email address"
    },
    "password": {
      "type": "string",
      "description": "User password"
    }
  },
  "required": [
    "login",
    "password"
  ]
}

Headers

Content-Type: application/json

Body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "JSON Web Token."
    }
  }
}

POST /auth/login Refresh a token

Allows to retrieve a new, valid JSON Web Token based on a valid JSON Web Token.

Expired tokens MUST NOT be refreshed.

Endpoint information
Requires authentication Yes
Has restricted scope No

Example URI

POST https://api.example.com/auth/login

Headers

Authorization: JWT <token>

Headers

Content-Type: application/json

Body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...."
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "New JWT"
    }
  }
}

User registration

POST /auth/register Register a new user

Creates a new user account.

  • Provided email address MUST be unique.

  • Passwords MUST have at least six characters.

  • Passwords MUST NOT contain the user name or parts of the user’s full name, such as his first name.

  • Passwords MUST use at least three of the four available character types: lowercase letters, uppercase letters, numbers, and symbols.

After successful registration a confirmation email MUST be sent to provided address.

Endpoint information
Requires authentication No

Error codes
400 4001 Password doesn't match password guidelines
400 3001 User already exists

Example URI

POST https://api.example.com/auth/register

Headers

Content-Type: application/json

Body

{
  "email": "john.doe@mail.com",
  "password": "QXR0mi38a2"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "E-mail address."
    },
    "password": {
      "type": "string",
      "description": "User password."
    }
  },
  "required": [
    "email",
    "password"
  ]
}

This has no content.

User

Current user profile

Current user MUST be identifed by JWT provided in request header.

GET /users/me Retrieve profile of the current user

Retrieves the profile of the current user.

Endpoint information
Requires authentication Yes
Has restricted scope No

Example URI

GET https://api.example.com/users/me

Headers

Authorization: JWT <token>

Headers

Content-Type: application/json

Body

{
  "id": "a6vhAo3FG7t1",
  "createdAt": "2016-07-01T15:11:09.553Z",
  "updatedAt": "2016-07-01T15:11:09.553Z",
  "email": "john.doe@mail.com",
  "facebookId": 888047057953991,
  "name": "John",
  "surname": "Doe",
  "avatar": null
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "enum": [
        "a6vhAo3FG7t1"
      ],
      "description": "Short non-sequential url-friendly unique id."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO Date/time string. When this resource was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO Date/time string. When this resource was last updated."
    },
    "email": {
      "type": "string",
      "description": "Login. Unique email address of the user."
    },
    "facebookId": {
      "type": [
        "number",
        "null"
      ],
      "description": "Facebook ID of the user if user account is linked to the Facebook account."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "First name of the user."
    },
    "surname": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last name of the user."
    },
    "avatar": {
      "type": [
        "string",
        "null"
      ],
      "description": "URL to user avatar."
    }
  },
  "required": [
    "id",
    "email"
  ]
}

PATCH /users/me Partialy update a profile of the current user

Updates a profile of the current user setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Endpoint information
Requires authentication Yes
Has restricted scope No

Example URI

PATCH https://api.example.com/users/me

Headers

Content-Type: application/json
Authorization: JWT <token>

Body

{
  "name": "Ben"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "First name of the user."
    }
  }
}

Headers

Content-Type: application/json

Body

{
  "id": "a6vhAo3FG7t1",
  "createdAt": "2016-07-01T15:11:09.553Z",
  "updatedAt": "2016-07-01T15:11:09.553Z",
  "email": "john.doe@mail.com",
  "facebookId": 888047057953991,
  "name": "John",
  "surname": "Doe",
  "avatar": null
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "enum": [
        "a6vhAo3FG7t1"
      ],
      "description": "Short non-sequential url-friendly unique id."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO Date/time string. When this resource was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO Date/time string. When this resource was last updated."
    },
    "email": {
      "type": "string",
      "description": "Login. Unique email address of the user."
    },
    "facebookId": {
      "type": [
        "number",
        "null"
      ],
      "description": "Facebook ID of the user if user account is linked to the Facebook account."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "First name of the user."
    },
    "surname": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last name of the user."
    },
    "avatar": {
      "type": [
        "string",
        "null"
      ],
      "description": "URL to user avatar."
    }
  },
  "required": [
    "id",
    "email"
  ]
}

User password

PUT /users/me/password Change a password of the current user

Changes user password.

After password is changed all access tokens issued for this user prior to password change must be invalidated.

Endpoint information
Requires authentication Yes
Has restricted scope No

Error codes
400 4001 Password doesn't match password guidelines

Example URI

PUT https://api.example.com/users/me/password

Headers

Content-Type: application/json
Authorization: JWT <token>

Body

{
  "old_password": "secret",
  "new_password": "$3C6e7"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "old_password": {
      "type": "string"
    },
    "new_password": {
      "type": "string"
    }
  },
  "required": [
    "old_password",
    "new_password"
  ]
}

This has no content.

User avatar

POST /users/me/avatar Set user avatar

Sets user avatar.

Either upload the raw binary ( media parameter) of the file, or its base64-encoded contents ( media_data parameter). Use raw binary when possible, because base64 encoding results in larger file sizes.

Endpoint information
Requires authentication Yes
Has restricted scope No

Error codes
400 2001 File is too large
400 2002 Unsupported file type

Example URI

POST https://api.example.com/users/me/avatar

Headers

Content-Type: multipart/form-data
Authorization: JWT <token>

This has no content.

DELETE /users/me/avatar Delete user avatar

Restores user avatar to the default one.

Endpoint information
Requires authentication Yes
Has restricted scope No

Example URI

DELETE https://api.example.com/users/me/avatar

Headers

Authorization: JWT <token>

This has no content.

Users

GET /users List all users

Returns a list of users. The users are returned in sorter order, with the most recently created user accounts appearing first.
Requires authentication Yes
Has restricted scope No

Example URI

GET https://api.example.com/users

Headers

Authorization: JWT <token>

Headers

Content-Type: application/json

Body

[
  {
    "id": "a6vhAo3FG7t1",
    "createdAt": "2016-07-01T15:11:09.553Z",
    "updatedAt": "2016-07-01T15:11:09.553Z",
    "email": "john.doe@mail.com",
    "facebookId": 888047057953991,
    "name": "John",
    "surname": "Doe",
    "avatar": null
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

User

GET /users/{id} Retrieve a user

Retrieves the details of an existing user.
Requires authentication Yes
Has restricted scope No

Error codes
400 1000 Referenced resource not found

Example URI

GET https://api.example.com/users/a6vhAo3FG7t1

URI Parameters

id

string  (optional)  Example: a6vhAo3FG7t1

id of the user.

Headers

Authorization: JWT <token>

Headers

Content-Type: application/json

Body

{
  "id": "a6vhAo3FG7t1",
  "createdAt": "2016-07-01T15:11:09.553Z",
  "updatedAt": "2016-07-01T15:11:09.553Z",
  "email": "john.doe@mail.com",
  "facebookId": 888047057953991,
  "name": "John",
  "surname": "Doe",
  "avatar": null
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "enum": [
        "a6vhAo3FG7t1"
      ],
      "description": "Short non-sequential url-friendly unique id."
    },
    "createdAt": {
      "type": "string",
      "description": "ISO Date/time string. When this resource was created."
    },
    "updatedAt": {
      "type": "string",
      "description": "ISO Date/time string. When this resource was last updated."
    },
    "email": {
      "type": "string",
      "description": "Login. Unique email address of the user."
    },
    "facebookId": {
      "type": [
        "number",
        "null"
      ],
      "description": "Facebook ID of the user if user account is linked to the Facebook account."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "First name of the user."
    },
    "surname": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last name of the user."
    },
    "avatar": {
      "type": [
        "string",
        "null"
      ],
      "description": "URL to user avatar."
    }
  },
  "required": [
    "id",
    "email"
  ]
}

This has no content.