Introduction
This document describes common usage of the Performio APIs, including authentication, HTTP verbs, expected error codes and responses. You will also find links to further documentation regarding the specific APIs available.
Overview
HTTP verbs
Performio APIs attempt to adhere as closely to REST standards and conventions as possible in regards to HTTP verbs. PATCH is not supported and all PUT operations are considered as a full update.
| Verb | Usage |
|---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Not supported |
|
Used to update an existing resource, full updates only |
|
Used to delete an existing resource |
HTTP status codes
Performio APIs attempt to adhere as closely to REST standards and conventions as possible in regards to HTTP status codes.
| Status code | Usage |
|---|---|
|
The request is successful. The response body is variable (e.g. a JSON representation of a resource). Commonly returned by GET methods. |
|
The request is successful. A new resource has been created. Commonly returned by POST methods. |
|
The request is successful but there is not content to be returned. Commonly returned by DELETE methods. |
|
The request is incorrect or malformed based on the clients input. The server has refused to process the request. The client should not repeat this request without modification. |
|
The request is incorrect as it is either missing a valid authentication header. The server has refused to accept your request. |
|
The request is well-formed, but part or all of the requested resource could not be found. |
|
The request is well-formed, but an internal condition is preventing its execution. |
|
The request has been deemed incorrect generally due to validation issues. The client should not repeat this request without modification. |
|
The called has made too many requests in a specific time period. The client should wait and repeat this request without modification. |
|
The server has encountered an unexpected error and cannot respond more meaningfully. |
Authentication
Performio APIs utilise OAuth 2.0 as an authentication method. In order to utilise the API the Client Credentials grant type is supported, which as defined by the OAuth 2.0 spec is used by clients to obtain an access token outside of the context of a user. In order to access a secure API, you must first obtain an authenticated token and then provide it with every subsequent request to the endpoints.
Before you get started
The first step of calling any API is to be issued with the appropriate API keys. You can request API keys for your instance from Performio support via Zendesk.
You will receive:
-
URL for your gateway (entry point to the APIs), i.e.
https://gateway-domain.performio.co/gateway-
ClientID, i.e.
5s5OQ61ATFZf2FWjSrdJ9A4Qs-
ClientSecret, i.e.
yFxRUxXKKLaLFjlvWE5QcG035bMLw4Ht5ldFQxsb17xFDQ8NSLObtaining a token
First step is to generate a bearer token. As mentioned, we use the Client Credentials grant which provides a bearer token valid for a certain amount of time, after which a new bearer token needs to be generated. No refresh token is supplied or required.
In order to obtain a token, follow these steps:
-
Obtain a ClientID and ClientSecret (credentials)
-
Base64 encode the ClientID and ClientSecret together as "<ClientID:ClientSecret>"
-
POST to the /oauth/token endpoint with your credentials as Basic HTTP Authentication header
For example, assuming that
-
Client id is 5s5OQ61ATFZf2FWjSrdJ9A4Qs
-
Client secret is yFxRUxXKKLaLFjlvWE5QcG035bMLw4Ht5ldFQxsb17xFDQ8NSL
-
Basic Authentication string is NXM1T1E2MUFURlpmMkZXalNyZEo5QTRRczp5RnhSVXhYS0tMYUxGamx2V0U1UWNHMDM1Yk1MdzRIdDVsZEZReHNiMTd4RkRROE5TTA==
Then your request would be:
$ curl 'https://gateway-domain.performio.co/gateway/oauth/token' -i -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Basic NXM1T1E2MUFURlpmMkZXalNyZEo5QTRRczp5RnhSVXhYS0tMYUxGamx2V0U1UWNHMDM1Yk1MdzRIdDVsZEZReHNiMTd4RkRROE5TTA==' \
-d 'grant_type=client_credentials'If successful, you will get a response that includes an authenticated access token, similar to:
{
"access_token" : "e9036e38-d67e-11e8-9f8b-f2801f1b9fd1",
"token_type" : "bearer",
"expires_in" : 86399,
"scope" : "read write trust"
}Using a token
Once you have obtained a token you must provide it with each request as a Bearer Authentication header to the API endpoints to gain access.
For example, assuming that
-
Access token is e9036e38-d67e-11e8-9f8b-f2801f1b9fd1
-
You wish to get a list of periods
Then your request would be:
$ curl 'https://gateway-domain.performio.co/gateway/calculation/v1/periods' -i -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \In the event of attempting to use an expired token, you will get a response that is similar to:
{
"error": "invalid_token",
"error_description": "Access token expired: e9036e38-d67e-11e8-9f8b-f2801f1b9fd1"
}Error Responses
Request exceptions produced from within the API will adhere to the following format:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 154
{
"timestamp" : 1617843928603,
"status" : 404,
"error" : "Not Found",
"message" : "Example exception text.",
"path" : "/v1/exception/standard"
}| Path | Type | Description |
|---|---|---|
|
|
Number representing the timestamp of the caught exception. |
|
|
Number representing the HTTP code of the exception. |
|
|
String representing the short hand error message associated with the exception. |
|
|
String representing the details of the exception. |
|
|
String representing the path to the resource causing the exception. |
Validation based exceptions produced form within the API will adhere to the following format:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
Content-Length: 246
{
"timestamp" : 1617843928669,
"status" : 422,
"error" : "Unprocessable Entity",
"message" : "Example exception text.",
"details" : [ "Description of first issue", "Description of second issue" ],
"path" : "/v1/exception/validation"
}| Path | Type | Description |
|---|---|---|
|
|
Number representing the timestamp of the caught exception. |
|
|
Number representing the HTTP code of the exception. |
|
|
String representing the short hand error message associated with the exception. |
|
|
String representing the details of the exception. |
|
|
String representing the path to the resource causing the exception. |
|
|
Array of Strings representing details for the exception. |
Transition from Calculation API
In order to clarify and standardise Performio’s API offering, the Calculation API has been split into three new APIs:
-
Metadata API is responsible for base resources
-
Errand API is responsible for what was called Jobs under the Calculation API, now Errands
-
Document API is responsible for file management
All legacy endpoints are accounted for in the new APIs, and following is a guide on how to transition over.
|
|
|
Batch Processes (the results of Jobs in the legacy Calculation API) have been wrapped in a new Errand resource. Request and response have been standardised across all Errand types. |
||
GET /metadata/v1/batches |
Batches have been separated from Calculations, and each Calculation type has its own endpoint. Results are paginated. |
|
POST /errand/v1/batches |
Calculation Jobs are now known as Calculation / Batch Errands. If you want to run a Calculation, create a Calculation Errand. If you want to run a Batch, create a Batch Errand. Request and response have been standardised across all Errand types; periodNumber request property has been replaced with periodRange, participantId request property has been replaced with participantIds or participantEids in the case of v2. |
|
Request and response have been standardised across all Errand types. Results are paginated. |
||
No changes. |
||
No changes. |
||
No changes. |
||
No changes. |
||
Response has been standardised. |
||
Response has been standardised. |
||
Import Jobs are now known as Import Errands. Request and response have been standardised; periodNumber request property has been replaced with periodRange. |
||
Import Jobs are now known as Import Errands. Request and response have been standardised; periodNumber request property has been replaced with periodRange. |
||
Results are paginated. |
||
Results are paginated. |
APIs
Metadata API
The Metadata API provides access to the basic resources found within Performio, i.e. Custom Tables, Participants, Periods etc. Further documentation is available here.
Document API
The Document API provides mechanisms to upload and manage files in Performio. Further documentation is available here.
Errand API
The Errand API provides mechanisms to send requests to the Calculation Engine to execute Calculations, Imports and Imported Data Deletes asynchronously. Further documentation is available here.
Extract API
The Extract API provides mechanisms to extract rows from Custom Tables utilising filters. Further documentation is available here.
Calculation API (Legacy)
The Calculation API has been deprecated, all endpoints have been replicated and improved in other APIs. Further documentation is available here.