Fhir basics session2_restful_apis

HL7 FHIR BASICS – SESSION 2
FHIR Restful APIs
22-May-2021
Presentation by Kumar Satyam

About Me
Kumar Satyam
• Chair Technical Committee @ HL7 India
• Member Education Advisory Committee @ HL7 International
• Interoperability Committee @Himss India
• Senior Architect – Interoperability @ Philips India
• Mail:- tc@hl7india.org
• LinkedIn :- https://www.linkedin.com/in/kumarsatyam/
• Twitter:- https://twitter.com/kr_satyam
22-May-2021

Acknowledgements & Credits
This Presentation borrows from the content of presentations by
➢Grahame Grieve
➢Lloyd McKenzie
➢Ewout Kramer
➢David Hay
➢ and other members of HL7 FHIR Community.
22-May-2021

Agenda
• Understand the FHIR Restful paradigm.
• Introduction to FHIR RESTful APIs
• Getting a look at the specification
• Tryout some APIs on test servers
22-May-2021

House Keeping
• Please be on mute while the session is in progress.
• Please use your full name in zoom participant's profile.
• Ask questions on zoom chat.
• Follow up & discussions on fhirindia forum.
• Everyone please ensure that you are on the discussion forum.
https://fhirindia.zulipchat.com/#narrow/stream/272723-Training-.26.20Conferences/topic/FHIR.20Basics.20Training
22-May-2021

About the course
22-May-2021

Course Design - Thought
• Community driven.
• Focus on getting started.
• Understand the important concepts.
• Participate , learn and build along with the community.
• Continuous learning
Important : This training is conducted as a FHIR India community initiative. This
training does not substitute any official training provided by HL7.
22-May-2021

Course layout
• 5 Sessions
• Introduction to Interoperability, HL7 Standards & Principles of FHIR
• What are FHIR Restful APIs
• Understanding FHIR Resources
• FHIR Conformance & Terminology
• FHIR Implementation Considerations
• 60 – 90 minutes duration.
• Online/ Virtual
22-May-2021

FHIR India Community
22-May-2021

What is FHIR India Community
• Open community of HL7 FHIR & Interoperability enthusiasts.
• #fhirIndia – social media tag.
• https://fhirindia.zulipchat.com/ - Discussion forum
• https://www.linkedin.com/groups/13932672/ - LinkedIn Group
10K by Dec 2021.
22-May-2021

Recap – Session 1
22-May-2021

Interoperability
Interoperability is ability of two or more systems or components to exchange information and to use the
information that has been exchanged (IEEE 1990)
• Technical Interoperability - Technology layer
• Semantic Interoperability - Data Layer
• Process & Clinical Interoperability - Human Layer
• The Institutional layer - culture, education, regulations ,incentives etc.
• Standards enable Interoperability.
22-May-2021

What is FHIR
• New Standard from HL7.
• Latest released version is R4.
• Resources are the basic building blocks
• Interoperability paradigms supported
by FHIR
• Restful API,
• Messaging,
• Documents
• Services
Specification:- https://www.hl7.org/fhir
F-Fast
H-Healthcare
I-Interoperability
R-Resources

The FHIR Manifesto
• Focus on Implementers.
• Target support for common scenarios.
• Leverage cross- industry web technologies.
• Require human readability as base level of interoperability.
• Make content freely available.
• Support multiple paradigms & architectures
Source : Principles of Health Interoperability_ SNOMED CT, HL7 and FHIR 3rd edition
22-May-2021

FHIR RESTful APIs
22-May-2021

Genesis of FHIR
• HL7 Fresh look Task force – 2011.
• What would healthcare exchange look like if we started from scratch using modern
approaches?
• Web search for success markers led to RESTful based APIs
• Exemplar: Highrise (https://github.com/37signals/highrise-api)
• Drafted a healthcare exchange API based on this approach
• Resources For Health: A Fresh Look Proposal
http://www.healthintersections.com.au/?p=502
22-May-2021

REST
Basic REST principles
• Uniform Interface
• Stateless Interactions
• Cacheable
• Client and Server
• Layered System
22-May-2021

FHIR RESTFul Paradigm
➢“REpresentational State Transfer”
➢Represent your data as “resources”
➢Make “Resource” URI addressable
➢Use HTTP methods to perform CRUD operations
➢FHIR extends the HTTP methods for additional base operations
➢Resources may be exchanged using different formatted representations
▪ XML, JSON, RDF,ND-JSON .
22-May-2021

Example use case
22-May-2021
Prescription
Prescription
ServiceRequest/DiagnosticReport
ServiceRequest/DiagnosticReport
Referral/ Discharge Summary

Instance Level
Allows a client to retrieve the current content of a
resource, to update the content to a new state, to
delete the resource, or to see its modification
history
Type Level
Allows a client to search through the existing
resources that already exist, create a new instance
of a resource, or get the history of all changes to
resource of the type.
System Level
Allows a client to determine what functionality is
provided by the system, perform batches and
transactions across multiple resource types, and
get the history of all changes to all resources.
22-May-2021 Presentation by Kumar Satyam
FHIR Base Services

A Typical FHIR URL
22-May-2021
https://server.org/fhir/Patient/1234
Structurally, this URL has three parts
[base-address]/[Type]/[id]
Note: This URL resolves to the current version of a resource. It’s also
specific to a server.
Base address
Type
id
base-
address
Identifies a FHIR System service. That is,
a server that that makes information
available in conformance with the FHIR
specification.
Type Identifies a FHIR Type service that
manages a collection of resources that
all have the same type. The type must
be one of those defined in the FHIR
specification.
Id Identifies a FHIR Instance service that
manages an instance of a resource
within the collection

FHIR GET
22-May-2021
• To Get a known Resource at a location
➢ REQUEST
GET https://server.org/fhir/Patient/1234 HTTP/1.1
Accept: application/fhir+xml;charset=utf-8
➢ RESPONSE
HTTP/1.1 200 OK
Content-Type: application/fhir+xml;charset=utf-8
Content-Length: 932
Last-Modified: Thu, 25 April 2019 13:45:32 GMT
<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir"><id value="example"/><meta><security><system value="http://terminology.hl7.org/CodeSystem/v3-
ActReason"/><code value="HTEST"/><display value="test health data"/></security></meta><identifier><system
value="urn:oid:1.2.36.146.595.217.0.1"/><value value="12345"/></identifier><active value="true"/><name><use value="official"/><family
value="Chalmers"/><given value="Peter"/><given value="James"/></name><telecom><system value="phone"/><value value="(03) 5555 6473"/><use
value="work"/><rank value="1"/></telecom><gender value="male"/><birthDate value="1974-12-25"/><deceasedBoolean value="false"/><address><use
value="home"/><line value="534 Erewhon St"/><city value="PleasantVille"/><district value="Rainbow"/><state value="Vic"/><postalCode
value="3999"/></address><managingOrganization><reference value="Organization/1"/></managingOrganization></Patient>
HTTP Verb +
Path
UTF-8
Encoding

FHIR POST
22-May-2021
POST https://server.org/fhir/Patient
endpoint
resource type
➢Format of the body defined and sent in the Content-Type header
➢Success response is a 201 (Created)
➢The Location header contains the newly assigned resource id and version id
➢The ETag header may also contain the newly assigned version id

POST Explained
• Create a Patient
22-May-2021
➢ REQUEST
POST https://server.org/fhir/Patient HTTP/1.1
Accept: application/fhir+xml;charset=utf-8
Body (Patient Resource)
➢ RESPONSE
HTTP/1.1 201 Created
Content-Length: 932
ETag: W/”1”
Location:
https://server.org/fhir/Patient/1234/_history/1
Last-Modified: Thu, 25 April 2019 13:45:32 GMT
Body (Patient or OperationOutcome Resource)
HTTP Verb +
Path
Assigned
version id
Operation
Status

FHIR PUT
• Updating a resource
22-May-2021
PUT https://server.org/fhir/Patient/1234
endpoint
resource type
➢PUT on the resource’s identifying URL
➢Format of the body defined and sent in the Content-Type header
➢Success response is a 200 (OK)
➢The Location header contains the newly assigned version id
➢The ETag header may also contain the newly assigned version id
id

Other Operations
➢Update as Create
➢Conditional Create
➢Conditional Update
➢Patch
➢Delete
➢Conditional Delete
22-May-2021

Transactions & Batch
• POST a Bundle to the server root: /
• The Bundle contains a collection of requests
• The requests are processed in order
• Temporary references between bundled resources possible
• A bundle of type ‘batch’ is processed non-atomically
• A bundle of type ‘transaction’ is processed atomically*
22-May-2021

OperationOutcome
22-May-2021
When something goes wrong … return the OperationOutcome resource

Operations
22-May-2021
http://hl7.org/fhir/operationslist.html

SEARCH
• Using GET
https://server.org/fhir/Patient?name=Smith
https://server.com/fhir/Observation?patient.name=Jones
22-May-2021
GET https://server.org/fhir/Patient?name=Smith
Note: No explicit ‘id’ in URL; instead, search criteria as URL parameters.
GET [base]/[type]{?[parameters]{&_format=[mime-type]}}
base
type
parameters

Search Parameters
22-May-2021
➢Each resource has a set of “standard” search parameters
▪ Found at the bottom of every resource definition page
▪ So, not all elements are searchable!
➢Patient example → http://hl7.org/fhir/patient.html#search All Resources
have common
parameters

Search results
22-May-2021
This Bundle is
a Searchset
Result

Search using POST
POST [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}
Content-Type: application/x-www-form-urlencoded
param1=value&param2=value
• Same semantics as the equivalent GET method
• Supports same search parameters in the URL path
• Also supports search parameters in an application/x-www-form-urlencoded
formatted request body
Note: application/x-www-form-urlencoded is supported for POST so that invoking a search by POST can be done
from HTML forms in a browser...
22-May-2021

Search Examples
• Scenario – How to search for and return all Observations for a given Patient
using the Patient’s name?
➢https://server.com/fhir/Observation?patient.name=Jones
Execute one search operation on the Observation resource
▪ Using the Observation “patient” search parameter
▪ Chain the Patient “name” parameter
22-May-2021

Search Example
• Scenario – We search for and return all Observations for a given date. How
do we include all the corresponding Patients?
➢https://server.com/fhir/Observation?date=2019-04-25
&_include=Observation:patient
22-May-2021
Execute one search operation on the Observation resource
▪ Use the Observation “patient” search parameter
▪ Include all referenced Patient resources

CapabilityStatement
➢Documents the capabilities of a FHIR client and
server
➢A client should examine the CapabilityStatement of
a server to determine its supported behavior
➢The CapabilityStatement:
➢ is a key part of the FHIR conformance framework
➢ is a statement of the features, rules and behaviors of a
FHIR system
➢ may be used for system compatibility testing, code
generation, or as the basis for conformance testing
➢To declare themselves “FHIR Conformant”, a system
MUST publish a CapabilityStatement
22-May-2021
GET [base]/metadata{?mode=[mode]} {&_format=[mime-type]}
➢ Which FHIR version?
➢ What Resources?
➢ What search parameters?
➢ What formats?
➢ Type of server/client
➢ Who can I contact?
➢ Software name
➢ …
http://hl7.org/fhir/http.html#capabilities

References & further reading
• https://martinfowler.com/articles/richardsonMaturityModel.html
• https://code.tutsplus.com/tutorials/http-the-protocol-every-web-developer-
must-know-part-1--net-31177
• https://code.tutsplus.com/tutorials/http-the-protocol-every-web-developer-
must-know-part-2--net-31155
• https://www.devdays.com/wp-
content/uploads/2020/12/gqbyu_201117_AbelEnthoven_FHIR_REST_API.pdf
22-May-2021

Fhir basics session2_restful_apis

Recommended

Recommended

More Related Content

Similar to Fhir basics session2_restful_apis

Similar to Fhir basics session2_restful_apis (20)

Recently uploaded

Recently uploaded (20)

Fhir basics session2_restful_apis