Getting Started with Box

After reading this guide and performing all steps, you will learn:

  • What is FHIR

  • How to create an instance of FHIR server

  • Basics of FHIR RESTful API

  • How to make secure requests to a FHIR server

Introduction

Basic Terms

  • FHIR is a platform specification that defines a set of entities and operations on those entities for interoperability between healthcare systems and applications

  • FHIR server is a web application implementing FHIR specification and providing RESTful API

  • Box is an instance of a FHIR server provided by any Aidbox product

Guide Assumptions

In this guide, we will be using Aidbox.Cloud for simplicity of Box creation, however any other Aidbox product will also work.

This guide assumes that you will set proper values instead of placeholders like this: <YOUR-BOX>

Create a Box

Choose how you would like to authorize Aidbox. It can be done via your GitHub or Google account.

After you have been successfully authorized in Aidbox.Cloud, click the 'New Box' button to start.

In the displayed form, enter your future box name. It can be a name of your application you are going to build. Then choose your plan and click the 'Create' button.

Your new box will be successfully created. Click the box name to proceed.

Check the CRUD

Now go to the REST Console section and let's see what we can do here.

REST console

REST console is designed to work with resources on your Box by sending HTTP requests in accordance with FHIR RESTful API. To do this, we need to type an HTTP verb (GET, POST, PUT, PATCH, DELETE) and the address of the resource (for example /Patientplease pay attention to the resource name written with a capital letter). In cases when you need to send the request body (e.g for a POST request), it is passed separated by empty line, in YAML or JSON format — you can choose both (request and response) content type by YAML | JSON switcher.

Create a Patient

Let's add a couple of new patients. For this, we type in our console POST /Patient and in the body of the request wherein we will send the data of our new patient (Aidbox supports JSON and few other formats but we will use YAML for compactness and readability):

Use the copy button in the top right corner of a code snippet to avoid copying of unnecessary white space characters.

Request
Response
POST /Patient
resourceType: Patient
name:
- given: [Max]
family: Turikov
gender: male
birthDate: '1990-10-10'
address:
- line:
- 123 Oxygen St
city: Hello
district: World
state: NY
postalCode: '3212'
telecom:
- use: home
- system: phone
value: "(32) 8934 1234"
use: work
rank: 1
Status: 201
name:
- given: [Max]
gender: male
address:
- city: Hello
line: [123 Oxygen St]
state: NY
district: World
postalCode: '3212'
telecom:
- {use: home}
- {use: work, rank: 1, value: (32) 8934 1234, system: phone}
birthDate: '1990-10-10'
id: 957d782d-3e40-4978-968c-63a1ef7d2473
resourceType: Patient
meta:
lastUpdated: '2018-10-29T09:09:16.604Z'
versionId: '118'
tag:
- {system: 'https://aidbox.io', code: created}

This is only an example, you can change values as you want. For more information check the full Patient resource description and official example. The id field in the request body is not required. and if you do not send it to the server, it will be generated. Description of the difference in the create operation behavior between FHIR and Aidbox endpoints can be found here.

Get a Patient

After sending the request, we receive a response with Status: 201 and the sent data which means that our patient has been created. We can make sure of this by sending the request GET /Patient/<id> and receive created patient data (in our case id is 957d782d-3e40-4978-968c-63a1ef7d2473, we got the id from the response), or we can check a complete list of patients — GET /Patient

Request
Response
GET /Patient/957d782d-3e40-4978-968c-63a1ef7d2473
Status: 200
name:
- given: [Max]
gender: male
address:
- city: Hello
line: [123 Oxygen St]
state: NY
district: World
postalCode: '3212'
telecom:
- {use: home}
- {use: work, rank: 1, value: (32) 8934 1234, system: phone}
birthDate: '1990-10-10'
id: 957d782d-3e40-4978-968c-63a1ef7d2473
resourceType: Patient
meta:
lastUpdated: '2018-10-29T09:09:16.604Z'
versionId: '118'
tag:
- {system: 'https://aidbox.io', code: created}

There are much more operations that can be done with a server using RESTful API but for our case to check if everything is set up properly and to get basic understanding of FHIR RESTful API, POST and GET requests are enough.

What's next?

Want to know more about Aidbox, FHIR or FHIR applications? Join our community chat (#aidbox channel).