Note
This guide uses curl for the example calls to the PainChek API. You can use any tool or programming environment that supports RESTful API calls.
Requests to the API should be made using the content type "application/json". The only exceptions to this are where images are concerned, these should be sent with as multipart content types.
Currently, there are 3 PainChek environments:
|
Environment |
Base URL |
Region |
Environment |
|---|---|---|---|
|
Production AP |
Asia Pacific |
Production |
|
|
UAT AP |
Asia Pacific |
User Acceptance Testing |
|
|
Production EU |
European Union |
Production |
Note
-
User Acceptance Testing environments can be used to develop and test applications/scripts that utilise the API
-
Production environments should only be accessed using tested applications/scripts. Any changes made via the API immediately impact the production instance and can't be undone
-
Contact PainChek support (support@painchek.com) if you are unsure as to which region you should be accessing
All examples in this documentation use the UAT AP base URL (https://ua.ap.painchek.com/). You'll need to replace that with the appropriate URL.
The PainChek API has been developed using Swagger, which according to wikipedia, is:
An open source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services
Swagger produces documentation of all of the methods available and is available here:
|
Environment |
AP Swagger URL |
EU Swagger URL |
|---|---|---|
|
UAT |
N/A |
|
|
Production |
In order to access the Swagger documentation, you must sign in to Django (the framework the PainChek API has been built on) - you can use any set of standard PainChek credentials. See Accessing the Swagger Documentation for more details.
To access the API, you'll need to be issued a set of API client details and a set of PainChek credentials. Once you have those, you fetch a token to use for the rest of your session.
The format, if using CURL, is:
curl \ -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \ -X POST https://ua.ap.painchek.com/api/integration/auth/ \ -d client_id="client1" \ -d client_secret="secret"
That call, if successful, returns a token:
{
"access_token": "n7wzioQY1u1jydOII8sNNxLukT4wXx",
"other fields": "..."
}
The token is then passed in the header of all calls to the API - e.g.:
curl -H "Authorization: Bearer n7wzioQY1u1jydOII8sNNxLukT4wXx" https://ua.ap.painchek.com/api/account/users/
For simplicity, the token is omitted from all of the examples in the document - i.e. the above command would be documented as:
curl https://ua.ap.painchek.com/api/account/users/
Note
See the Authentication and Tokens section for more details.
To list the all of the users in your PainChek instance, you can issue this command (remembering you'll need to add the "-H "Authorization: Bearer <token>"" parameter as previously mentioned):
curl https://ua.ap.painchek.com/api/account/users/
Sample return data:
{
"count": 2,
"next": null,
"previous": null,
"results": [{
"uuid": "c0d06995-87dd-4437-a92e-338f53b7dba5",
"license": "a89e0cc1-fd90-4721-b09b-7f527f5ff626",
"license_name": "A89E0CC1-FD90/ePAT Technologies Ltd/2018-08-25",
"email": "user_e@painchek.com",
"first_name": "User",
"last_name": "E",
"phone": "",
"institution": null,
"institution_name": null,
"position": "",
"avatar": null,
"has_activated": true,
"role": "user",
"is_active": true,
"date_joined": "2017-08-28T12:13:38.364000Z",
"modified_at": "2017-09-01T07:49:55.055000Z",
"external_id": null
}, {
"uuid": "e9c57efe-f3e1-48c9-af90-15bf8ff8bde2",
"license": "a89e0cc1-fd90-4721-b09b-7f527f5ff626",
"license_name": "A89E0CC1-FD90/ePAT Technologies Ltd/2018-08-25",
"email": "user_d@painchek.com",
"first_name": "User",
"last_name": "D",
"phone": "",
"institution": null,
"institution_name": null,
"position": "",
"avatar": null,
"has_activated": true,
"role": "admin",
"is_active": true,
"date_joined": "2017-08-28T12:13:08.351000Z",
"modified_at": "2017-09-27T00:47:41.540000Z",
"external_id": null
}]
}
That's a typical response format from the API when a list of data - users, patients, assessments, etc. - is requested (see Common API Fields and Structures for more details).
You can request the details for a single object - e.g. a particular user - by including their identifier (uuid) in the URL. e.g. to fetch the details for user "c0d06995-87dd-4437-a92e-338f53b7dba5", you can issue this command:
curl https://ua.ap.painchek.com/api/account/users/c0d06995-87dd-4437-a92e-338f53b7dba5/
In this case, just the details for that user are returned:
{
"uuid": "c0d06995-87dd-4437-a92e-338f53b7dba5",
"license": "a89e0cc1-fd90-4721-b09b-7f527f5ff626",
"license_name": "A89E0CC1-FD90/ePAT Technologies Ltd/2018-08-25",
"email": "user_e@painchek.com",
"first_name": "User",
"last_name": "E",
"phone": "",
"institution": null,
"institution_name": null,
"position": "",
"avatar": null,
"has_activated": true,
"role": "user",
"is_active": true,
"date_joined": "2017-08-28T12:13:38.364000Z",
"modified_at": "2017-09-01T07:49:55.055000Z",
"external_id": null
}
You can see these are exactly the same details that were returned for user "c0d06995-87dd-4437-a92e-338f53b7dba5" when the full list of users was returned.