API

This document is intended to give a general introduction to the API. Note that the API is dynamic, and is highly dependent on which modules and features that are installed and enabled on individual sites. As such, this document should help you get started, but you may wish to explore the setup of the particular sites that you are integrating with, in order to determine which types and fields that are available.

Generally speaking, almost everything can be read and written using the API. Some types and fields may have restricted access, so you may only see particular fields when using a proper Request elevation. Encrypted data (like passwords) are unavailable through the API.

API requests follow the following URL format:

https://example.com/piranyaplatform/data/{type}.{format}

Example:

https://example.com/piranyaplatform/data/User.json

The following formats are supported:

• csv - read-only
• json
• pdf - read-only
• xml

Authentication

Authentication should be done using the Authorization HTTP header. Both Basic (username, password) and Bearer (access token) are supported.

Request elevation

By default requests are made on behalf of the user that is authenticated. If no user is authenticated then the request is made as if it is viewed publicly and will thus only include public information.

Requests can be elevated by passing the mode parameter (or elevation, which is an alternative naming).

The following values are supported and are ordered from least elevated to most elevated:

• Public
• Unauthenticated
• User - Must be logged in
• Client - A registered user/account performing actions as a client/customer
• ClientDepartment (Deprecated, use Client instead) - A department performing actions as a client (usually of another department)
• ProviderDepartment - A department who is a provider of something, e.g. one that is able to provide/sell products in a shop
• ReaderDepartment - Read-only access to a department
• OwnerDepartment - Must have access to manage one or more departments
• Admin - Must be an administrator to use this elevation

User and Client elevation

User elevation is used when accessing information owned by the user, such as their home address, editing their profile or placing orders.

Client elevation is used when viewing or placing orders as a registered client in e.g. a shop.

If the authenticated user (e.g. an admin) has access to multiple accounts, then an account id can be specified using the header Authorization-Account or by passing the parameter for_account_id

Department elevations

Department elevations are used when executing a request on behalf of a department.

This is useful when, for example:

• Creating products that are owned (and thus managed) by a specific department (OwnerDepartment elevation).
• Viewing and managing orders being sold by a department (ProviderDepartment)
• Read-only viewing of orders or products from a department (ReaderDepartment)

Users can be granted access to departments, and do not need to be administrators.

If the authenticated user has access to multiple departments, then a department id can be specified using the HTTP header Authorization-Department or by passing the parameter for_department_id.

Admin elevation

This elevation is used when reading or writing data not owned by departments or when bypassing department restrictions as an administrator of a site.

Note that some data may still have limited or no access - even for administrators.

Generic parameters for all request types

• api_version is used to specify the version of the api and its structure. Default is 3
• depth specifies the recursion level and how "deep" data should be read. Default is 1 and means that no relations should be resolved. 2 would, for example, mean that one level more should be resolved - for a user that could mean that addresses for the user should also be fetched (depth 2) and not just the user itself (depth 1). Higher values for depth results in longer query time so try to keep values as low as possible to get the data you need.
• elevation or mode is an enum indicating who the request is made for. Read more in the above section.
• limit is a number used for pagination and limits the maximum number of items returned in a single request. Default is unlimited, but a recommended value is 100.
• offset is a number used for pagination and indicates how many items should be skipped. If limit is 100 then setting offset to 100, 200, 300 would show page 2, 3, 4. Default is 0 (first page).

Response structure

Succesful (non-error) responses are given with the following structure:

{
  "api_version": 3,
  "data": [
    {
      "name": "Alice",
    },
    {
      "name": "Bob",
    }
  ],
  "locale": "en",
  "result": "ok"
}

The data field in the response is always an array, regardless of whether a single entity or multiple entities are returned.

Error responses

If encountering a server-side error, the following error response structure is returned:

{
  "api_version": 3,
  "error": "Friendly message with information about the error",
  "error_code": 123,
  "locale": "en",
  "result": "error"
}

Query

Example: https://example.com/piranyaplatform/data/User.json?api_version=3&depth=2

Returns the current user (since mode is user - the default). Most fields are hidden for brevity.

{
  "api_version": 3,
  "data": [
    {
      "id": 16294,
      "created_at": "2020-12-15T08:47:53+01:00",
      "username": "test@piranya.dk",
      "profile": {
        "first_name": "Test",
        "middle_name": null,
        "last_name": "Testsen",
        "email": "test@piranya.dk",
        "primary_phone": "+4512345678"
      }
    }
  ],
  "locale": "da",
  "result": "ok"
}

Almost all fields can be used for filtering in the API so you could for exanple find users with a specific email address (as an admin) using:

https://example.com/piranyaplatform/data/User.json?api_version=3&depth=2&mode=admin&email=test@piranya.dk

Note that mode is admin since we are asking for details for other users.

Insert

To create, for example, a new product we could perform the following POST request:

https://example.com/piranyaplatform/data/Product.json

Parameters:

• api_version=3
• depth=2 (depth of the data returned after inserting)
• mode=admin
• payload (which, in addition to data, can also contain all parameters above)

{
  "data": [
    {
      "system_identifier": "SKU1234",
      ...
    }
  ]
}

Update

Update or PUT requests behave very similarly to POST requests above. The updated entity (with new values) should just be added within the data array but should of course have IDs or keys so the system knows which entity to update.

Delete

Deletes also have a similar format to POST and PUT requests, but only require entities to specify their key and not necessaryly all values for the fields.

E.g. a DELETE request with the payload below would delete the entity that has the ID 1234.

{
  "data": [
    {
      "id": 1234
    }
  ]
}