API Reference Manual

Content

Authentication:

• Users authentication

Collections behaviour:

• Filtering on collection
• Sorting on collection
• Pagination on collection

Errors:

• General description

Authentication

Users authentication

API supports Bearer Authentication (token authentication) with JSON Web Token (JWT). JWT is issued by the server in response to a sign-in request (session create). The client must send this token in the Authorization header in order to authenticate himself:

Authorization: Bearer <token>

Token is exposed to the client only once after fresh session is created and should be securely stored in user's client application.

General endpoint behaviour

Embedding

Some resources also support embedding of some relationships or additional properties. To embed something, use embed argument in url query with value consisting of embeded fields separated by comma. For example, to embed relationship role_ids and roles_count, use ?embed=role_ids,roles_count in URL query of your request. Embedding is possible either for requests on collections and single model (for all methods available).

Embedded fields are returned within object of a model as a dictionary in property _embedded.

{
  "id": 1,
  "_embedded": {
    "role_ids": [1,4],
    "roles_count": 2
  }
}

Collections behaviour

Filtering

Filters can be used on most resources returning collection of some data. There is a lot of variations how to filter data, so filters must be encoded in base64.

There are defined basic operations to compare values while filtering:

Operator	Description	Limitations
eq	equals (==)	Can be used with every type.
neq	not equals (!=)	Can be used with every type.
in	one of the values must equal	Can only be used with array. Does not make sense for bool[].
gt	greater than (>)	Can be used only with int, decimal, date.
gte	greater than or equal to (>=)	Can be used only with int, decimal, date.
lt	less than (<)	Can be used only with int, decimal, date.
lte	less than or equal to (<=)	Can be used only with int, decimal, date.
contains	checks string contains substring	Can be used only with string.
starts_with	checks string starts with substring	Can be used only with string.
ends_with	checks string ends with substring	Can be used only with string.

And these basic types:

Type	Description	Operators supported
string	sequence of characters	eq, neq, in, starts_with, ends_with, contains
int	64 bit integer	eq, neq, in, gt, gte, lt, lte
enum	enumerator or model identifier, int or string	eq, neq, in
bool	boolean, true or false	eq, neq
decimal	number with fixed decimal point	eq, neq, in, gt, gte, lt, lte
date	Date or DateTime	eq, neq, in, gt, gte, lt, lte

Filter object has following structure:

Param	Type	Description
f	string[]	For each specified field filter will be applied with operator o and value v.
o	string	Operator that should apply.
v	any	Value of filter. For operator in can be array, for other operators must be scalar value.

One or more filter object have to be put into single array and encoded to base64 before sending as a value of filters URL parameter.

Example:

We want to get only records with identifiers 1, 5 and 24:

First, filters collection has to be created:

[
    {
        "f": ["id"],
        "o": "in",
        "v": [1, 5, 24]
    }
]

Than, this collection has to be JSON encoded and than encoded to base64 like this (equal signs can be omitted):

W3siZiI6WyJpZCJdLCJvIjoiaW4iLCJ2IjpbMSw1LDI0XX1d

and send it as fitlers URL parameter:

GET /api/resource?filters=W3siZiI6WyJpZCJdLCJvIjoiaW4iLCJ2IjpbMSw1LDI0XX1d HTTP/1.1

Sorting

For sorting, send URL parameter sort with name of columns you want to sort. For ascending sorting use ?sort=column_name, for descending sorting use minus sign before column name, like ?sort=-column_name.

Sorting is supported for multiple columns at once - columns must be separated by comma sign, like ?sort=-column_a,column_b.

Pagination

Some resources might be paginated by default. For turning pagination on or off just use URL parameter paginated - value 1 turns pagionation on, value 0 turns pagination off.

By default, there are 20 items per one page. This can be changed by specifying number of items per page with URL parameter per_page.

To change the page send URL parameter page with required page number.

Errors

General description

All errors will have same structure:

Param	Type	Description
id	string	A unique identifier for this particular occurrence of the problem.
type	string	An application-specific error code, expressed as a string value.
message	string	Human-readable summary of the problem. Can be localized.
errors	FieldError[]	An array of errors related to particular fields in request. This field is present when 422 error is returned.

Example #1:

{
    "type": "NotFound",
    "message": "Required model was not found.",
    "id": "0cd85449-05fe-4866-9802-8192e6785fc7"
}

Example #2:

{
    "type": "ValidationError",
    "message": "The given data was invalid.",
    "id": "5c99f70a-e400-44bb-9cd4-592b0a30e145",
    "errors": [
        {
            "field": "email",
            "message": "The email field is required."
        }
    ]
}