6. API v2 (future)

This is a complete rewrite of the v1 API to make it more readable and easier to understand.

Caution

While this version of the API is cleaner, it's still a work-in-progress and is not yet complete. If you are missing any functionality, please refere to v1 API instead.

Anything available, though, is final and will not change and is ready to use in your application.

The endpoints of this API are structured around specific entities -- it is, in a way -- more "restful" than the previous API.

Note

Slash at the end of the URL is ignored

v2 endpoints ignore the trailing slash. This means that URIs /api/v2/companies/self/ and /api/v2/companies/self are considered equal.

The endpoints are hierarhical and take on the following structure:

/{entity}/{query-type}[/{identifier}] # Get/act on a single entity
/{entity}/list/                       # Get the list of entities

where:

  • {entity} is the plurar name of the entity, e.g companies, users etc.
  • {query-type} is the query by which the entity can be uniquely identified. Check the specific API call for which queries are supported. Most of the time, at least these two types will be available:
    • …/self/… refers to the entity of the caller. e.g. /companies/self will return the company connected with the credentials of the caller.
    • …/by-id/{id}/… with find the given entity by id, if the caller has access to it. E.g. /companies/by-id/7 returns the company with id=7.
  • /list returns a list of all entities matching the given criteria. This creteria is sometimes defined with the query string and sometimes inferred from the context. Check specific API calls for description.