Exivity API v1

🚀

This is the Exivity API specification, and should be used as a reference guide for creating requests and parsing responses. For a more general introduction to Exivity, please refer to our documentation.

This API uses principles and constraints of REST APIs and on top of that, most resource endpoints listen to and responds with data structures as defined by the JSON:API standard. You'll recognise these endpoints when the documentation lists the following headers:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Authentication

Authentication against the API is done through a stateless JWT token, sent along as an Authentication header. To obtain a token, a request to the API endpoint /auth/token should be made with the user credentials. The JWT token will expire after one week for security reasons.

Example:

Authorization: Bearer [token]

Authorization

Some endpoints require a different set of permissions than others. If insufficient permissions are granted to the authenticated user, a 403 Forbidden response is returned.

JSON:API interface

Some requests using the JSON:API format accept additional query string parameters.

Include related resources

Inclusion of related resources in the response can be requested with the include query string parameter. Multiple entities can be specified by separating them with a comma (U+002C). Each endpoint definition specifies which includes can be requested.

Examples:

GET /user?include=usergroup,accounts
GET /user/[id]?include=usergroup,accounts

Alternatively, related resources on a single resource can be requested through a separate endpoint:

GET /user/[id]/usergroup

Pagination

When making requests to endpoints which can return more than one entity, results are paginated. The number of results per page and the requested page can be adjusted with the page[limit] and page[offset] query string parameters. When the page limit is set to -1, all results are returned. The links element in the JSON response contains references to URLs which can be used to navigate the resultset. The meta element in the JSON response contains a reference to the total number of items in the resultset.

Example:

GET /user?page[limit]=50&page[offset]=2

Sorting

It is possible to sort results by using the sort query string parameter. A descending sort order can be requested by prefixing a hyphen (U+002D).

Example:

GET /user?sort=-username

Filtering

To filter results, use the filter[attribute] query string parameter. A filter can also use related entities (which don't have to be included in the request with the include parameter).

The following formats are supported for filtering results:

Token Description Example
^ Field starts with filter[name]=^John
$ Field ends with filter[name]=$Smith
~ Field contains filter[favorite_cheese]=~cheddar
< Field is less than filter[lifetime_value]=<50
> Field is greater than filter[lifetime_value]=>50
>= Field is greater than or equals filter[lifetime_value]=>=50
<= Field is less than or equals filter[lifetime_value]=<=50
= Field is equal to filter[username]==Specific%20Username
!= Field is not equal to filter[username]=!=common%20username
[...] Field is one or more of filter[id]=[1,5,10]
![...] Field is not one of filter[id]=![1,5,10]
NULL Field is null filter[address]=NULL
NOT_NULL Field is not null filter[email]=NOT_NULL

Example:

GET /user?filter[usergroup.permissions]=~MANAGE_USERS&filter[email_address]=$example.com

Related resources

Relationships data on resources can be queried and modified by using the /[resource]/[id]/relationships/[relation] endpoint structure.

Error responses

HTTP error responses (4xx, 5xx) will contain status information in JSON format, i.e.:

Example:

{
  "errors": [
    {
      "status": "422",
      "title":  "Attribute validation error",
      "detail": "Password must contain at least 8 characters."
    }
  ]
}

Possible response codes:

Code Description
400 Bad request Something in the request is missing or invalid
401 Unauthorized JWT token is missing or invalid
403 Forbidden Missing required permission for this operation
404 Not found Entity can't be found
409 Conflict Entity type or id doesn't match endpoint
422 Unprocessable Entity Parameters validation error

Rate limits

The rate at which you can make requests to the API is limited by client IP address, and is limited at 10 requests per second. The API allows for short request bursts (i.e. you can exceed this limit for a short period of time). If you've exceeded your API rate limit, you'll get back a 503 Service Unavailable response.

Terms of service

You can find the terms of service on our website.

PUBLISHER

Exivity
Exivity provides metering and billing solutions covering any IT service delivery model. It enables you to generate a single bill of IT.

Imports

30+