REST API

Users and Groups REST API

Same tasks can be performed programmatically via REST API.

POST /users

Creates new user.

Example Request:

POST https://[box-name].aidbox.io/users?access_token=[access-token] Accept: application/json Content-Type: application/json {"email": "user@example.com", "password": "godloveskittens", "data": "{}"}

Example Response:

{  "data": null,  "password": "$s0$f0801$PAPMyIhrU98utG2MFZN66w==$L6xOyD4seflK3hzQtQLAQJ6U1PP01x/ciDvSQnxfVIg=",  "email": "user@example.com",  "status": null,  "id": 2 } // HTTP/1.1 201 Created // Server: nginx // Date: Thu, 05 May 2016 10:38:44 GMT // Content-Type: application/json // Content-Length: 152 // Connection: keep-alive // Request duration: 0.307818s

In case of invalid data you'll receive 422 Unprocessable Entity status:

{  "entity": {    "data": "{}",    "password": "godloveskittens",    "email": "user@example.com"  },  "errors": {    "email": [      "email is already taken"    ]  } } // HTTP/1.1 422 Unprocessable Entity // Server: nginx // Date: Thu, 05 May 2016 10:49:06 GMT // Content-Type: application/json // Content-Length: 126 // Connection: keep-alive // Request duration: 0.514180s

GET /users

Returns list of existing box users.

Example Request:

GET https://[box-name].aidbox.io/users?access_token=[access-token]

Example Response:

[  {    "group-ids": [],    "groups": null,    "data": "{ }",    "email": "user@example.com",    "status": null,    "id": 2  } ] // HTTP/1.1 200 OK // Server: nginx // Date: Thu, 05 May 2016 10:51:55 GMT // Content-Type: application/json // Content-Length: 180 // Connection: keep-alive // Request duration: 0.403116s

GET /users/[id]

Retrieves data for specific user.

Example Request:

GET https://[box-name].aidbox.io/users/2?access_token=[access-token]

Example Response:

{  "groups": [],  "data": null,  "password": "$s0$f0801$PAPMyIhrU98utG2MFZN66w==$L6xOyD4seflK3hzQtQLAQJ6U1PP01x/ciDvSQnxfVIg=",  "email": "user@example.com",  "status": null,  "id": 2 } // HTTP/1.1 200 OK // Server: nginx // Date: Thu, 05 May 2016 12:53:39 GMT // Content-Type: application/json // Content-Length: 164 // Connection: keep-alive // Request duration: 0.192518s

PUT /users/[id]

Updates existing user.

Example Request:

PUT https://[box-name].aidbox.io/users/2?access_token=[access-token] Accept: application/json Content-Type: application/json {"data": null, "password": "new-password", "email": "user@example.com"}

Example Response:

{  "data": null,  "password": "$s0$f0801$z7Q1dw22tyH5lkHTVSf0hQ==$NpBEXBOCbHty4cURu0FIm7rcSUCTXE3tHaPnE4fT5Ms=",  "email": "user@example.com",  "status": null,  "id": 2 } // HTTP/1.1 200 OK // Server: nginx // Date: Thu, 05 May 2016 13:06:19 GMT // Content-Type: application/json // Content-Length: 152 // Connection: keep-alive // Request duration: 0.357732s

DELETE /users/[id]

Deletes specific user. Returns data of deleted user.

Example Request:

DELETE https://[box-name].aidbox.io/users/2?access_token=[access-token]

Example Response:

{  "data": null,  "password": "$s0$f0801$z7Q1dw22tyH5lkHTVSf0hQ==$NpBEXBOCbHty4cURu0FIm7rcSUCTXE3tHaPnE4fT5Ms=",  "email": "user@example.com",  "status": null,  "id": 2 } // HTTP/1.1 200 OK // Server: nginx // Date: Thu, 05 May 2016 13:07:35 GMT // Content-Type: application/json // Content-Length: 152 // Connection: keep-alive // Request duration: 0.387985s

FHIR Server REST API

General REST Information

Server Root URL

In FHIR Specification all REST actions are relative to Server Root URL, which itself described in [FHIR-2.1.0.1] and refered as [base] in other parts of Specification. When using Aidbox, Server Root URL is composed in following way:

http(s)://<box-name>.aidbox.io/fhir

For box named example Server Root URL will be http(s)://example.aidbox.io/fhir.

HTTP and HTTPS

Both HTTP and HTTPS are supported, but we strongly recommend our users to use HTTPS for reasons of data safety.

Authorization and Authentication

Aidbox uses OAuth for authenticating clients, so in most cases you should provide access_token param in query string or request headers. Proceed to OAuth Section for more comprehensive coverage of this topic.

For Authorization purposes Aidbox uses policies which are explained in detail in Security Section. For testing purposes, it's often useful to have just one policy which allows anonymous access to all FHIR URLs.

Request and Response Formats

[FHIR-2.1.0.6] declares both XML and JSON as valid formats for request and response bodies. Hovewer, Aidbox supports only JSON for now.

Resources CRUD

GET /fhir/[type]/[id]

[FHIR-2.1.0.8]: Reads current version of specific resource.

GET /fhir/[type]/[id]/_history/[vid]

[FHIR-2.1.0.9]: Reads historical version of specific resource.

GET /fhir/[type]/[id]/_history/[vid]

[FHIR-2.1.0.9]: Reads historical version of specific resource.

PUT /fhir/[type]/[id]

[FHIR-2.1.0.10]: Updates existing resource or creates new one with client-defined ID. When updating existing resource performs optimistic locking via checking of meta.versionId.

DELETE /fhir/[type]/[id]

[FHIR-2.1.0.12]: Deletes resource.

POST /fhir/[type]

[FHIR-2.1.0.13]: Creates new resource. Supports conditional create via If-None-Exist header.

Search

GET /fhir/[type]?[parameters]

[FHIR-2.1.0.14]: Searches a set of resources based on some filter criteria.

History

GET /fhir/[type]/[id]/_history

[FHIR-2.1.0.17]: Returns history of specific resource.

GET /fhir/[type]/_history

[FHIR-2.1.0.17]: Returns history of all resources of specific type.

Other

GET /fhir/metadata

[FHIR-2.1.0.15]: Returns Conformance Resource describing available interactions of this FHIR Server.

POST /fhir

[FHIR-2.1.0.16]: Performs atomic set of operations (transaction) on arbitrary FHIR Resources.

GET /fhir/ValueSet/[id]/$expand

[FHIR-6.24.18.1]: Expands ValueSet.

Not Supported FHIR Features

Below is list of features not yet supported by Aidbox FHIR Server:

  • XML format support
  • Messaging [FHIR-2.4]
  • GET /fhir/_history history of all resource types
  • GET /fhir/_search search through all available resources
  • Searching by _text and _content attributes
  • Expanding ValueSets containing references to external NamingSystems (LOINC, SNOMED, etc)