πŸŽ“ Getting Started with Devbox in Cloud

In this article, you will learn about the FHIR standard essentials, including:

  • 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 Devbox in Cloud for simplicity of the 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

Devbox in Cloud is a sandbox version of Aidbox in HealthSamurai cloud. Each Box is a private instance of a FHIR server with a separate database and domain. You can create multiple boxes for testing and evaluation.

Please, pay attention, that the sandbox environment doesn't fit for any kind of production usage. The service availability and data integrity are not guaranteed. Do not put any PHI data there.

To try out Devbox in Cloud, open https://aidbox.app/​

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

If you chose Github authorization, click the 'Authorize HealthSamurai' button.

Github will ask you to confirm your password to continue.

And now you are successfully authorized in Devbox in 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. It will be the base URL of your FHIR server.

Choose the desired FHIR version, and click the 'Create' button.

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

​

Now you can browse the left navigation menu and work with your box and its database. What you can do here:

  • Settings β€” view your box settings, base URL, manage your collaborators.

  • Resources β€” view the list of available resources.

  • Operations β€” view the list of available operations.

  • Database β€” work with your database.

  • REST console β€” execute REST requests to your box.

  • Auth clients β€” manage your auth clients.

  • Users β€” manage your box users.

  • Access Control β€” manage access to your box.

  • Concepts β€” view the list of available concepts.

  • Documentation β€” redirects you to the docs.aidbox.app site with documentation.

  • Support β€” this is a modal form to send a feedback.

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 /Patient β€” please 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 a 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 unnecessary white space characters.

Request
Response
Request
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
Response
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, and 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. A 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 check 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
Request
GET /Patient/957d782d-3e40-4978-968c-63a1ef7d2473
Response
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 many more operations you can execute using RESTful API but it’s enough to use POST and GET requests to check if everything is set up right.

What's next?

Want to know more about Aidbox, FHIR or FHIR applications? Join our community chat.