CRUD

Common operations create, read, update, and delete.

This part of documentation describes how to create, read, update, and delete resources. Also, it covers some advanced topics like conditional create, update, and delete. Aidbox REST API slightly differs from canonical FHIR REST API. There is the article which describes those differences.

All sample requests can be run from the Postman collection:Run in Postman

Introduction

A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it (information about it can be found in FHIR specification or through Aidbox metadata). In most cases a resource represented as a JSON/XML/YAML document.

Each resource has its own resource type, this type defines a set of data which can be stored with this resource, and possible relationships with other resources.

Attribute is a part of the resource definition which describes what fields can or must be present in the resource document, type of such fields, and their cardinality.

Every resource type has the same set of interactions available. These interactions are described below.

Each interaction can fail with:

  • 403 Forbidden — client is not authorized to perform the interaction

create

POST [base]/[type]

This is one of the most basic interactions which gives an ability to create resources. It uses POST HTTP method, accepts a resource type via path parameters, and resource as a body of the request. A response to this interaction may be one of the following:

  • 201 Created — resource successfully created

  • 400 Bad Request — resource could not be parsed or failed basic FHIR validation rules

  • 409 Conflict — resource with such id already exists

  • 422 Unprocessable Entity — the proposed resource violated applicable FHIR profiles or server business rules

A successful response (2xx) also contains a created resource as a body and additional headers Location, ETag, Last-Modified which contain full path to resource (base url, resource type and id of newly created resource), additionally information about version (vid) and modification time of that resource.

Location: [base]/[type]/[id]/_history/[vid]
ETag: [vid]
Last-Modified: [modification-datetime]

An unsuccessful response (4xx) contains OperationOutcome resource which describes issues server faced during creation of this resource.

201 Created

Request
Response
POST /Patient
name: [{given: ["Bob"]}]

Status: 201

name:
- given: [Bob]
id: 17b69d79-3d9b-45f8-af79-75f958502763
resourceType: Patient
meta:
lastUpdated: '2018-11-29T10:44:10.588Z'
versionId: '13'
tag:
- {system: 'https://aidbox.app', code: created}

422 Unprocessable entity

Request
Response
POST /Patient
name: "Bob"

Status: 422

resourceType: OperationOutcome
errors:
- path: [name]
message: expected array
warnings: []

Aidbox REST API doesn't ignoreid and treat it as all other attributes in contrast to FHIR API. Read more about differences here.

conditional create

POST [base]/[type]?[search parameters]

Much more complex way to create a resource (it requires knowledge of search) but it gives some additional flexibility. If you provide search parameters, create becomes conditional create and works in the following way (depending on the number of search results):

  • No matches: The server performs a create interaction

  • One Match: The server returns the found resource and 200 OK

  • Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough

200 OK

Create a patient if there is no patient with name Bob.

Request
Response
POST /Patient?name=Bob
name: [{given: ["Bob"]}]
gender: male

Status: 200

name:
- given: [Bob]
id: 17b69d79-3d9b-45f8-af79-75f958502763
resourceType: Patient
meta:
lastUpdated: '2018-11-29T10:44:10.588Z'
versionId: '13'
tag:
- {system: 'https://aidbox.app', code: created}

A patient was not created, an existing patient was returned.

read

GET [base]/[type]/[id]

One of the most basic interactions used to obtain a resource by a given id. For more advanced options for getting resources check out Search.

  • 200 OK — resource successfully found and returned

  • 404 Not Found — resource with a given id doesn't exist on the server

  • 410 Gone — resource was deleted

200 OK

Get an existing patient:

Request
Response
GET /Patient/17b69d79-3d9b-45f8-af79-75f958502763

Status: 200

name:
- given: [Bob]
id: 17b69d79-3d9b-45f8-af79-75f958502763
resourceType: Patient
meta:
lastUpdated: '2018-11-29T10:44:10.588Z'
versionId: '13'
tag:
- {system: 'https://aidbox.app', code: created}

404 Not Found

Attempt to get a non-existing patient:

Request
Response
GET /Patient/some-not-existing-id

Status: 404

resourceType: OperationOutcome
status: 404
text: Resource Patient/some-not-existing-id not found

vread

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

This is another read interaction but it returns a specific version resource. Similar to read but additionally requires to specify version id.

200 OK

Version id 13 was extracted from the response of a create interaction.

Request
Response
GET /Patient/17b69d79-3d9b-45f8-af79-75f958502763/_history/13

Status: 200

name:
- given: [Bob]
id: 17b69d79-3d9b-45f8-af79-75f958502763
resourceType: Patient
meta:
lastUpdated: '2018-11-29T10:44:10.588Z'
versionId: '13'
tag:
- {system: 'https://aidbox.app', code: created}

update

PUT [base]/[type]/[id]

This is interaction which allows to modify existing resource (create a new version of it). After performing this interaction, the resource will be replaced with a new version of resource provided in the body of the request. id of a resource can't be changed (at least cause of versioning) and id in the body of the resource is ignored in update interaction (it's done to make a conditional update possible without knowing logical id of the resource). If a resource with id (provided in the url) doesn't exist, new resource will be created. Following codes can be returned by the server:

  • 200 OK — resource successfully updated

  • 201 Created — resource successfully created

  • 422 Unprocessable Entity — the proposed resource violated applicable FHIR profiles or server business rules

200 OK

Update a patient by given id:

Request
Response
PUT /Patient/17b69d79-3d9b-45f8-af79-75f958502763
name: [{given: ["Bob"]}]

Status: 200

name:
- given: [Bob]
id: 17b69d79-3d9b-45f8-af79-75f958502763
resourceType: Patient
meta:
lastUpdated: '2018-11-29T13:58:03.875Z'
versionId: '38'
tag:
- {system: 'https://aidbox.app', code: updated}

201 Created

Create a patient with specified id:

Request
Response
PUT /Patient/tom-id
name: [{given: ["Tom"]}]

Status: 201

name:
- given: [Tom]
id: tom-id
resourceType: Patient
meta:
lastUpdated: '2018-11-29T14:01:09.336Z'
versionId: '40'
tag:
- {system: 'https://aidbox.app', code: created}

versioned update

While you do update there is a risk of override latest changes done by another operation. To escape this situation you can use versioned update by sending with update If-Match header with versionId of resource you want to update. If server has same version of resources update will be successful, if versions do not match - you will get OperationOutcome with conflict code.

Example

Let say we created patient:

create-patient-request
POST /Patient
id: pt-1
name: [{family: ['Wrong']}]
status: 201
resourceType: Patient
id: pt-1
meta: {lastUpdated: '2019-04-04T09:15:25.210Z', versionId: '30'}
name:
- {family: Wrong}

Now to fix family for this patient without risk override someone else changes - we use versioned update request:

versioned-update-request
PUT /Patient/pt-id
If-Match: 30
name: [{family: ['Smith']}]

If someone already touched same patient, his version id was changed and we get OperationOutcome.

conflict-response
status: 409
resourceType: OperationOutcome
id: conflict
text: {status: generated, div: Version Id mismatch}
issue:
- {severity: fatal, code: conflict, diagnostics: Version Id mismatch}

conditional update

PUT [base]/[type]?[search parameters]

This is more complex way to update a resource but it gives more power. It gives the ability to update a resource without knowing id but requires knowledge of Search. Different response codes will be returned (based on the number of search results):

  • No matches: The server performs a create interaction

  • One Match: The server performs the update against the matching resource

  • Multiple matches: The server returns a 412 Precondition Failed error indicating the client's criteria were not selective enough

200 OK

Update the patient by name.

Request
Response
PUT /Patient?name=Tom
name: [{given: ["Tom"]}]
gender: male

Status: 200

name:
- given: [Tom]
gender: male
id: tom-id
resourceType: Patient
meta:
lastUpdated: '2018-11-29T14:10:31.885Z'
versionId: '42'
tag:
- {system: 'https://aidbox.app', code: updated}

201 Created

Create a patient with the name Julie and specified id if no other patients with the same name exist:

Request
Response
PUT /Patient?name=Julie
id: julie-id
name: [{given: ["Julie"]}]
gender: female

Status: 201

name:
- given: [Julie]
gender: female
id: julie-id
resourceType: Patient
meta:
lastUpdated: '2018-11-29T14:13:03.416Z'
versionId: '43'
tag:
- {system: 'https://aidbox.app', code: created}

If a patient with name Julie already exists, update interaction will be performed and id will be ignored.

delete

DELETE [base]/[type]/[id]

This interaction deletes a resource, responds with 200 OK on a successful delete, but on deletion of an already deleted resource it responds with 204 No Content.

To get 204 No Content always instead of 200 OK, use _no-content=true query parameter.

  • 200 OK — resource successfully delete

  • 204 No Content — resource already deleted

200 OK

Delete a patient by id:

Request
Response
DELETE /Patient/tom-id

Status: 200

name:
- given: [Tom]
gender: male
id: tom-id
resourceType: Patient
meta:
lastUpdated: '2018-11-29T14:33:17.429Z'
versionId: '44'
tag:
- {system: 'https://aidbox.app', code: deleted}

204 No Content

Attempt to delete an already deleted resource:

Request
Response
DELETE /Patient/tom-id

Status: 204

conditional delete

DELETE [base]/[type]?[search parameters]

Depending on the number of resources meeting the search criteria, different actions will be performed and response codes will be returned:

  • No matches: Respond with 404 Not Found

  • One Match: The server performs an ordinary delete on the matching resource

  • Multiple matches: Servers respond with 412 Precondition Failed error indicating the client's criteria were not selective enough