Getting Started with SPA

Last updated last month

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

  • What is FHIR and SPA

  • How to create an instance of FHIR server

  • Basics of FHIR RESTful API

  • How to make secure requests to a FHIR server

  • How to create a new SPA and connect it 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

  • SPA is a single-page application that runs in a user web browser, in our case it will be a project on Angular

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

Guide Assumptions

This guide assumes that you have already installed git, npm, postman, and have a terminal application.

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.

Give Access to External Clients

Aidbox products support OAuth2.0 authorization framework and Access Control mechanism to provide ability for developers to create applications which can interact securely with Boxes (Aidbox FHIR server instances). For a single-page application, it's a common practice to use OAuth2.0 Implicit Grant flow.

To implement this flow, we need to create 3 entities:

  • User — the person who will log in and use application

  • Client — our single-page application which will interact with a FHIR server

  • AccessPolicy — set of rules which describes who and how can access FHIR server

Why so much moves needed to simply access a FHIR resource using an external client? Ask Aidbox developers and people in our community chat (#aidbox channel).

We will create all three entities with one request (don't forget to change admin password!):

Request
Response
POST /
type: transaction
entry:
- resource:
id: admin
email: "admin@mail.com" # Change this value
password: "password" # Change this value
request:
method: POST
url: "/User"
- resource:
id: SPA
redirect_uri: http://localhost:4200
request:
method: POST
url: "/Client"
- resource:
engine: json-schema
schema:
type: object
required:
- user
request:
method: POST
url: "/AccessPolicy"
Status: 200
id: '119'
type: transaction-response
resourceType: Bundle
entry:
- resource:
secret: null
redirect_uri: http://localhost:4200
id: SPA
resourceType: Client
meta:
lastUpdated: '2018-10-29T09:23:59.396Z'
versionId: '119'
tag:
- {system: 'https://aidbox.io', code: created}
status: 201
- resource:
email: admin@mail.com
password: $s0$f0801$JH/e5UHpObbWXY/UnnDX+A==$5czycStbfIx2MF4SX7jQpkCxBKtwxPU7QkJQHizUGiE=
id: admin
resourceType: User
meta:
lastUpdated: '2018-10-29T09:23:59.396Z'
versionId: '119'
tag:
- {system: 'https://aidbox.io', code: created}
status: 201
- resource:
engine: json-schema
schema:
type: object
required: [user]
id: 85d32690-77b6-45ba-be73-0dab60b1212a
resourceType: AccessPolicy
meta:
lastUpdated: '2018-10-29T09:23:59.396Z'
versionId: '119'
tag:
- {system: 'https://aidbox.io', code: created}
status: 201

We created the Client resource with redirect URI equal to our SPA address, the admin User with the password password, and AccessPolicy that tells to authorize any registered user.

Get an Access Token

Now we can request a token from our box using OAuth2.0 implicit grant flow.

Change the <YOUR-BOX> placeholder to the name of your box, and open the following URL in your browser.

https://<YOUR-BOX>.aidbox.app/oauth2/authorize?response_type=token&client_id=SPA&redirect_uri=http://localhost:4200/

box10 is a box name in my case

Enter email and password of the User, click 'Sign In', and you will be redirected to localhost:4200 (redirect_uri of SPA client).

Copy access_token value, we will use it to obtain Patient resource with external http client.

Check the access

Open Postman or any other http client, create new GET request, enter following url: https://<YOUR-BOX>.aidbox.app/Patient and add Authorization header with value equal to Bearer <YOUR-ACCESS-TOKEN-HERE>.

You should get a bundle with Patient resources. Yay! It seems to work.

Create FHIR SPA

On the final step we will configure and start our SPA. Make sure that you have Git and Node.js installed.

git --version # checks if git and other packages installed
# git version 2.15.2 │
node --version
# v8.9.4
npm --version # node package manager
# 5.6.0
git clone https://github.com/HealthSamurai/aidbox-angular-sample.git
cd aidbox-angular-sample
vim environment.ts # or use any other editor of your choice
# to set AIDBOX_URL var to https://<YOUR-BOX>.aidbox.app
npm install # install all project dependencies
npm install -g @angular/cli # install angular utilities
ng serve # start a web server for our SPA on the 4200 port
# or
ng serve --port 4242 # start a web server for our SPA on the specified port

Open http://localhost:4200, you automatically will be redirected to your box OAuth2.0 login page. Log in with email and password you set for your admin User previously.

It works! You are awesome!

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