API

All types are accessible through the API using the following format for urls:

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

Example:

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

The following formats are supported:

• csv - read-only
• json - supports all request types
• pdf - read-only
• xml - supports all request types

Authentication

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

While logged in you can create an access token using https://example.com/users/accesstoken?infinite=true

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 elevation parameter (previously called mode in older versions of the platform).

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 performing actions as a client/customer
• ClientDepartment - 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
• Unrestricted - Must be a super user

User elevation

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

Department elevation

The Department elevation is used when executing a request on behalf of a department. This is useful when, for example, creating products that are sold by specific departments. The user does not need to be an admin but only needs permission to access the department and can use the Department elevation to tell the system that the product is created for and owned by a department and not the user itself.

Departments can be specified using the HTTP header Authorization-Department (value is a department id) 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.

Data may still be restricted in such a way that the administrator is only able to read or edit specific information but all of the commonly used data is usually available.

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).

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,
  "locale": "da",
  "data": [
    {
      "id": 16294,
      "created": "2020-12-15T08:47:53+01:00",
      "username": "test@piranya.dk",
      "email": "test@piranya.dk",
      "profile": {
        "first_name": "Test",
        "middle_name": null,
        "last_name": "Testsen",
        "email": "test@piranya.dk",
        "primary_phone": "+4512345678"
      }
    }
  ],
  "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
    }
  ]
}