Eu-Ihis Ehr Restful API Final en

Hospital Health Information System – EU HIS
Contract No. IPA/2012/283-805
EHR RESTful API

Final version – July 2015
Target Audience:
EHR Developers
EHR Administrators
EPR Systems Developers
This document has been produced with the financial assistance of the European Union.
The views expressed herein can in no way be taken to reflect the official opinion of the European Union.
This project is funded by Republic of Serbia Implemented by the

the European Union Ministry of Health WHO and UNOPS
Abbreviation list
CDA Clinical Document Architecture

HL7 Health Level Seven International (healthcare informatics interoperability standards)
EHR Electronic Health Record
FHIR Fast Health Interoperable Resources
HIS Hospital Information System
HTTP Hypertext Transfer Protocol
IHIS Integrated Health Information System
ISO International Organization for Standardization
JSON JavaScript Object Notation
MIME Multipurpose Internet Mail Extensions
REST Representational State Transfer
UNOPS United Nations Office for Project Services
URI Uniform Resource Identifier
URL Uniform Resource Locator
XML Extensible Markup Language
XSLT Extensible Stylesheet Language Transformations
IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

EU-IHIS | Šumatovačka 78-80, Beograd, Serbia | www.eu-ihis.rs | +381 11 2449 565 1/24
Contents
1. INTRODUCTION ....................................................................................................................................... 4
2. RESTFUL PRINCIPLES ................................................................................................................................ 4
2.1 USE HTTP METHODS EXPLICITLY ....................................................................................................... 4

2.2 BE STATELESS ...................................................................................................................................... 4
2.3 EXPOSE DIRECTORY STRUCTURE-LIKE URIS ..................................................................................... 5
2.4 TRANSFER XML, JSON, OR BOTH ...................................................................................................... 5
3. EHR RESTFUL API COMMON CONCEPTS................................................................................................... 6
3.1 URL OPERATIONS STYLE GUIDE ......................................................................................................... 6

3.2 SERVICE ROOT URL............................................................................................................................. 6
3.3 HTTP STATUS CODES ......................................................................................................................... 6
3.4 CONTENT TYPES AND ENCODINGS....................................................................................................... 7
3.5 RESOURCE-LEVEL INTERACTIONS........................................................................................................ 7
3.5.1 Read ............................................................................................................................................ 7
3.5.2 Create .......................................................................................................................................... 8
3.5.3 Update ......................................................................................................................................... 8
3.5.4 Delete .......................................................................................................................................... 9
3.5.5 Search ....................................................................................................................................... 10
3.6 SEARCH / QUERY ................................................................................................................................ 10
3.6.1 Parameters for each resource ............................................................................................... 10
3.6.2 Search parameter types ......................................................................................................... 10
3.6.2.1 Modifiers ................................................................................................................................................ 11
3.6.2.2 Number .................................................................................................................................................. 11
3.6.2.3 Date........................................................................................................................................................ 11
3.6.2.4 String ...................................................................................................................................................... 13
3.6.2.5 Token ..................................................................................................................................................... 13
4. RESOURCES ........................................................................................................................................... 13
4.1 ADMINISTRATIVE RESOURCES ............................................................................................................ 13

4.1.1 Patient ....................................................................................................................................... 14
4.1.1.1 Create..................................................................................................................................................... 14
4.1.1.2 Update ................................................................................................................................................... 15
4.1.1.3 Delete ..................................................................................................................................................... 15
4.1.2 Practitioner ................................................................................................................................ 16
4.1.2.1 Create..................................................................................................................................................... 16
4.1.2.2 Update ................................................................................................................................................... 16
4.1.2.3 Delete ..................................................................................................................................................... 17
4.2 CLINICAL RESOURCES......................................................................................................................... 17
4.2.1 Encounter .................................................................................................................................. 18
4.2.1.1 Search .................................................................................................................................................... 18
4.2.1.2 Create..................................................................................................................................................... 19
4.2.1.3 Read ....................................................................................................................................................... 20
4.2.1.4 Update ................................................................................................................................................... 20
4.2.1.5 Delete ..................................................................................................................................................... 20
4.2.2 Hospitalization .......................................................................................................................... 21
4.2.2.1 Search .................................................................................................................................................... 21
4.2.2.2 Create..................................................................................................................................................... 22

4.2.2.3 Read ....................................................................................................................................................... 22
4.2.2.4 Update ................................................................................................................................................... 23
4.2.2.5 Delete ..................................................................................................................................................... 23
4.2.3 Patient Summary ..................................................................................................................... 23
4.2.3.1 Search .................................................................................................................................................... 24
List of Tables
Table 1: HTTP status codes .............................................................................................................................. 7

Table 2: Resource level interactions................................................................................................................. 7
Table 3: Read interaction – Common HTTP status codes returned ................................................................... 8
Table 4: Create interaction – Common HTTP status codes returned ................................................................ 8
Table 5: Update interaction – Common HTTP status codes returned ............................................................... 9
Table 6: Delete interaction – Common HTTP status codes returned ................................................................ 9
Table 7: Search parameters types .................................................................................................................. 11
Table 8: Administrative resources.................................................................................................................. 14
Table 9: Patient resource – Supported interactions ....................................................................................... 14
Table 10: Practitioner resource – Supported interactions .............................................................................. 16
Table 11: Clinical resources ............................................................................................................................ 18
Table 12: Encounter resource – Supported interactions................................................................................. 18
Table 13: Encounter resource – Supported search parameters ...................................................................... 19
Table 14: Hospitalization resource – Supported interactions ......................................................................... 21
Table 15: Hospitalization resource – Supported search parameters............................................................... 22
Table 16: Patient Summary resource – Supported interactions...................................................................... 24
Table 17: Patient Summary resource – Supported search parameters ........................................................... 24

1. Introduction
Representational State Transfer (REST) defines a set of architectural principles used in Web Services
design with a focus on a system's resources, including how resource states are addressed and
transferred over HTTP by a wide range of clients written in different languages.
A concrete implementation of a RESTFul Web Service follows four basic design principles:
• Use HTTP methods explicitly.
• Be stateless.
• Expose directory structure-like URIs.
• Transfer XML, JavaScript Object Notation (JSON), or both.
The practical advantages of RESTful architectures include light-weight interfaces that allow for faster
transmission and processing of data structures. RESTful interfaces also facilitate faster development
cycles through their simpler structures.
Resources and their base operations very closely resemble the operation of a relational database –
information structures are defined, operations on creating, updating, deleting and retrieving data is
defined but the meaning of the data in an application is defined at a higher level.
2. RESTFul Principles
The following sections expand the four basic design principles to be followed in the implementation
of a REST Web Services and propose a technical rationale for why they might be important for REST
Web Service designers.
2.1 Use HTTP Methods Explicitly

One of the key characteristics of a RESTful Web Service is the explicit use of HTTP methods in a way
that follows the protocol as defined by RFC 2616. HTTP GET, for instance, is defined as a data-
producing method that's intended to be used by a client application to retrieve a resource, to fetch
data from a Web server, or to execute a query with the expectation that the Web server will look for
and respond with a set of matching resources.
REST asks developers to use HTTP methods explicitly and in a way that's consistent with the protocol
definition. This basic REST design principle establishes a one-to-one mapping between create, read,
update, and delete (CRUD) operations and HTTP methods. According to this mapping:
• To create a resource on the server, use POST.
• To retrieve a resource, use GET.
• To change the state of a resource or to update it, use PUT.
• To remove or delete a resource, use DELETE.
2.2 Be Stateless
REST Web Services need to scale to meet increasingly high performance demands. Clusters of
servers with load-balancing and failover capabilities, proxies, and gateways are typically arranged in
a way that forms a service topology, which allows requests to be forwarded from one server to the

other as needed to decrease the overall response time of a Web Service call. Using intermediary
servers to improve scale requires REST Web Service clients to send complete, independent requests;
that is, to send requests that include all data needed to be fulfilled so that the components in the
intermediary servers may forward, route, and load-balance without any state being held locally in
between requests.
A complete, independent request doesn't require the server, while processing the request, to
retrieve any kind of application context or state. A REST Web Service application (or client) includes
within the HTTP headers and body of a request all of the parameters, context, and data needed by
the server-side component to generate a response. Statelessness in this sense improves Web Service
performance and simplifies the design and implementation of server-side components because the
absence of state on the server removes the need to synchronize session data with an external
application.
2.3 Expose Directory Structure-Like URIs

From the standpoint of client applications addressing resources, the URIs determine how intuitive
the REST Web Service is going to be and whether the service is going to be used in ways that the
designers can anticipate. A third RESTful Web Service characteristic is all about the URIs.
REST Web Service URIs should be intuitive to the point where they are easy to guess. Think of a URI
as a kind of self-documenting interface that requires little, if any, explanation or reference for a
developer to understand what it points to and to derive related resources. To this end, the structure
of a URI should be straightforward, predictable and easily understood.
One way to achieve this level of usability is to define directory structure-like URIs. This type of URI is
hierarchical, rooted at a single path, and branching from it are subpaths that expose the service's
main areas. According to this definition, an URI is not merely a slash-delimited string, but rather a
tree with subordinate and superordinate branches connected at nodes. For example, in a discussion
threading service that gathers topics ranging from Java to paper, you might define a structured set of
URIs like this:
http://www.myservice.org/discussion/topics/{topic}
2.4 Transfer XML, JSON, or Both

A resource representation typically reflects the current state of a resource, and its attributes, at the
time a client application requests it. Resource representations in this sense are mere snapshots in
time. This could be a thing as simple as a representation of a record in a database that consists of a
mapping between column names and XML tags, where the element values in the XML contain the
row values. Or, if the system has a data model, then according to this definition a resource
representation is a snapshot of the attributes of one of the things in system's data model. These are
some of the REST Web Service purposes.
The last set of constraints that goes into a RESTful Web Service design has to do with the format of
the data that the application and service exchange in the request/response payload or in the HTTP
body. This is where it really pays to keep things simple, human-readable, and connected.

The objects in data model are usually related in some way, and the relationships between data
model objects (resources) should be reflected in the way they are represented for transfer to a client
application. In the discussion threading service, an example of connected resource representations
might include a root discussion topic and its attributes, and embed links to the responses given to
that topic.
3. EHR RESTful API Common Concepts

3.1 URL Operations Style Guide
URL operations in a RESTful environment are defined like:
OPERATION [base]/[type]/[id] {?_format=[mime-type]}
• OPERATION – HTTP verb used for operation

• Base – The service root URL
• Mime-type – the mime-type
• Type – resource name
• Id – Id of a resource
• Parameters – URL parameters as defined for particular operation
3.2 Service Root URL

The service root URL is the address where all of the resources defined by this interface are found and
takes the form of:
http(s)://server{/path}
The path part is optional. Each resource type defined in this specification has manager which can be
accessed like “/[type]” where the type is the name of the resource.
For the Serbian EHR system, the service root URL is defined like:
http(s)://ehr.eu-ihis.rs/ehr
All the logical interactions are defined relative to the service root URL. This means that if the address
of any one EHR resource on a system is known, the address of other resources may be determined.
3.3 HTTP Status Codes

This specification makes rules about the use of specific HTTP status codes in particular circumstances
where the status codes SHALL map to particular states correctly, and only where the correct status
code is not obvious. Other HTTP status codes may be used for other states as appropriate, and this
particularly includes various authentication related status codes and redirects. Authentication
redirects should not be interpreted to change the location of the resource itself (a common web
programming error).

Used HTTP status codes are divided following the rule:
Code Group Code Type
2XX Success
4XX Client error
5XX Server error
Table 1: HTTP status codes
3.4 Content Types and Encodings

Content types, also known as MIME Types, indicate the "type" associated with the message body's
byte sequence. The formal MIME-type for EHR resources is application/hl7-v3+xml. The correct
mime type SHALL be used by clients and servers:
Content-Type
application/hl7-v3+xml
3.5 Resource-Level Interactions

Each resource type has its set of interactions. All interactions are performed using an HTTP
request/response.
The following interactions are supported for resources:
Interaction Description
Read Read the current state of the resource.
Create Create new resource.
Update Update the current state of the resource by its Id.
Delete Delete resource by its Id.
Search Search resource type by some searching criteria.
Table 2: Resource level interactions
3.5.1 Read
The read interaction accesses the current contents of a resource. The interaction is performed by an
HTTP GET command as shown:
GET [base]/[type]/[id]

This returns a single instance with the content specified for the resource type.
Common HTTP status codes returned on EHR read interaction:
HTTP code Description
Resource is successfully retrieved. Requested resource is contained in
200 OK
response body.
404 Not Found Resource type not supported or not EHR endpoint.
Requested resource is no longer available in the EHR. (e.g., the resource has
410 Gone
been deleted from EHR).
Table 3: Read interaction – Common HTTP status codes returned
3.5.2 Create
The create interaction creates a new resource in a server assigned location. The create interaction is
performed by an HTTP POST command as shown:
POST [base]/[type]
The server returns a 201 Created, along with a Location header which contains the new logical Id of
the created resource:
Location: [base]/[type]/[id]
[id] is the newly created Id for the resource. When the payload data is incorrect and cannot be used
to create a new resource, the server returns a 422 Unprocessable Entity error code.
Common HTTP status codes returned on EHR create interaction are:
Resource is successfully created. Logical Id of the created resource is
201 Created
given by a Location header field.
400 Bad Request Resource could not be parsed.
405 Method Not Allowed Creation of the proposed resource is not allowed.
Server refuses to create a resource because of reasons specific to that
409 Conflict
resource (e.g., the resource already exists).
The proposed resource failed applicable EHR document validation or
422 Unprocessable Entity
EHR server rules.
Table 4: Create interaction – Common HTTP status codes returned
3.5.3 Update
The update interaction creates a new current version for an existing resource. The update
interaction is performed by an HTTP PUT command as shown:

PUT [base]/[type]/[id]
If the interaction is successful, the server SHALL return either a 200 OK if the resource was updated,
with a Last-Modified header.
Servers are permitted to reject update interactions because of integrity concerns or business rules
implemented on the server, and return HTTP status codes accordingly (usually 422). A server
SHOULD accept the resource as submitted when accepts the update.
Common HTTP status codes returned on EHR update interaction are:
200 OK Resource is successfully updated.
400 Bad Request Resource could not be parsed.
404 Not Found Resource type not supported, or not EHR endpoint
405 Method Not Allowed Update of specified resource is not allowed.
Server refuses to update a resource because of reasons specific to
409 Conflict
that resource (e.g., referential integrity).
The proposed resource failed applicable EHR document validation or
422 Unprocessable Entity
EHR server rules.
Table 5: Update interaction – Common HTTP status codes returned
3.5.4 Delete
The delete interaction removes an existing resource. The interaction is performed by an HTTP
DELETE command as shown:
DELETE [base]/[type]/[id]
A delete interaction means that non-version specific reads of a resource return a 410 error and that
the resource is no longer found through search interactions.
Common HTTP status codes returned on EHR delete interaction are:
200 OK Resource is successfully deleted.
404 Not Found Resource with specified Id is not found on the server.
405 Method Not Allowed Deletion of specified resource is not allowed.
Server refuses to delete a resource because of reasons specific to that
409 Conflict
resource (e.g., referential integrity).
Resource requested to be deleted is no longer available on the server
410 Gone
(e.g., the resource has been previously deleted).
Table 6: Delete interaction – Common HTTP status codes returned

3.5.5 Search
This interaction searches a set of resources based on some filter criteria. The interaction can be
performed by several different HTTP commands. To search all resources at once:
GET [base]?[parameters]
To search a single resource type:

GET [base]/[type]?[parameters]
GET [base]/[type]/_search?[parameters]
If the search fails, the return value is a status code 4xx or 5xx with description of the error. If the
search succeeds, the return contains the results of the.
3.6 Search / Query

One operation that is fundamental is to search (find existing resources by filter criteria) or query
(more detailed questions based on existing data). Search/query operations can span complexity
from a simple search based on indexed criteria, through to complex decision support based
requests, and finally complex queries that can only be resolved by human intervention.
In the simplest case, a search is executed by performing a GET operation in the RESTful framework:
GET [base]/[resourcetype](?[parameters])
For this RESTful search, the parameters are a series of name=[value] pairs encoded in the URL. A
HTTP status code of 403 signifies that the server refused to perform the query, while some other 4xx
or 5xx code signifies that some error occurred.
3.6.1 Parameters for each resource

Each resource defines its own set of search parameters with their names, types, and meanings.
These search parameters are defined together with resource definitions, and can be seen in the
Resources chapters.
Some of the search parameters defined by the resources are associated with more than one path in
the resource. This means that the search parameter matches if any of the paths contain matching
content, and which ever path matches, the whole resource is returned in the search results. The
client may have to examine the resource to determine which path contains the match.
3.6.2 Search parameter types

Each search parameter has its type which defines how the parameter behaves. EHR supports next
types of parameters:
Type Description
Number Search parameter SHALL be a number (a whole number, or a decimal).
Search parameter is on a date/time. The date format is the standard XML
Date
format, though other formats may be supported.

Search parameter is a simple string, like a name part. Search is case-
String
insensitive.
Search parameter on a coded element or identifier. May be used to search
through the text, displayname, code and code/codesystem (for codes) and
Token
label, system and key (for identifier). Its value is either a string or a pair of
namespace and value, separated by a "|", depending on the modifier used.
Table 7: Search parameters types
The search parameters can have modifiers that can control their behaviour. The modifiers depend of
the parameter type.
3.6.2.1 Modifiers
Parameters are defined per resource, and their names may additionally specify a modifier as a suffix,
separated from the parameter name by a colon. Modifiers are:
• For all parameters (except combination): ":missing". E.g. gender:missing=true (or false).
Searching for "gender:missing=true" will return all the resources that don't have any value for
the gender parameter (which usually equates to not having the relevant element in the
resource). Searching for "gender:missing=false" will return all the resources that have a value for
the "gender" parameter.
• For string: ":exact" (the match needs to be exact, no partial matches, case sensitive and accent-
sensitive), instead of the default behaviour, which is that the search does partial matches. It is at
the discretion of the server whether to do a left-partial search.
• For token: ":text" (the match does a partial searches on the text portion of a CodeableConcept
or the display portion of a Coding), instead of the default search which uses codes.
3.6.2.2 Number
The prefixes >, >=, <=, and < may be used on the parameter value, and have the usual meaning. Note
that "=" must be escaped in the value in a URL. Examples:
[parameter]=100 Values that equal 100.
[parameter]=<100 Values that are less than 100.
[parameter]=<=100 Values that are less or equal to 100.
[parameter]=>100 Values that are greater than 100.
[parameter]=>=100 Values that are equal or greater than 100.
3.6.2.3 Date
A date parameter searches on a date/time or period. The prefixes >, >=, <=, and < may be used on
the parameter value, and have the usual meaning. However, as is usual for date/time related
functionality, while the concepts are relatively straight-forward, there are a number of subtleties
involved in ensuring consistent behaviour.
• The date parameter format is yyyy-mm-ddThh:nn:ss(TZ) (the standard XML format).

• Technically, this is any of the date, dateTime, and instant data types.
• Any degree of precision can be provided, but it SHALL be populated from the left (e.g. can't
specify a month without a year), except that the minutes SHALL be present if an hour is
present, and you SHOULD provide a time zone if the time part is present.
• [parameter]=[date] searches for resources where the date is within the period implied by the
given value in [date]. [parameter]=>[date] searches for all resources where the specified date is
after [date]. [parameter]=<=[date] searches for all resources where the specified date is in or
before [date], etc.
• The element the search refers to may have a datatype of date, dateTime, and instant. All of
these time related types actually specify an interval of time, as does the search parameter itself.
• For a date or a dateTime (and the search parameter), the interval is implicit. For example,
the date 2013-01-10 specifies all the time from 00:00 on 10-Jan 2013 to immediately before
00:00 on 11-Jan 2013.
• An instant (which is the same as a fully specified dateTime with milliseconds) is considered a
fixed point in time with an interval smaller than the precision of the system, i.e. an interval
with an effective width of 0.
• Date parameter searches are always matched based on the behaviour of intervals, as follows:
• For [parameter]=[date], the requirement is that the search interval fully contains the time of
the target. i.e. [parameter]=2013-01-14 includes 2013-01-14T00:00 (obviously) and also
2013-01-14T10:00 but not 2013-01-15T00:00.
• For [parameter]=<[date], the requirement is that the interval of the time before [date]
intersects (i.e. overlaps) with the interval of time in the relevant resource element. For
instance, the resource time 2013-01-14 is included in the set of values that come before
2013-01-14T10:00, because it includes the part of 14-Jan 2013 before 10am.
• For [parameter]=>[date], the requirement is that the interval of the time after [date]
intersects (i.e. overlaps) with the interval of time in the relevant resource element. For
instance, the resource time 2013-01-14 is included in the set of values that come after 2013-
01-14T10:00, because it includes the part of 14-Jan 2013 after 10am.
Implicitly, a missing lower boundary is 'less than' any actual date. A missing upper boundary
is 'greater than' any actual date. For instance, the period from 21-Jan 2013 onwards is
included in matches for date=>=2013-03-14 because it may include times after 14-Mar 2013.
• Similarly, when the date parameter is not fully specified, matches against it are based on the
behaviour of intervals, where:
• Dates with just the year specified are equivalent to an interval that starts at the first instant
of January 1st to the last instant of December 31st, e.g. 2000 is equivalent to an interval of
[2000-01-01T00:00, 2000-12-31T23:59];
• Dates with the year and month are equivalent to an interval that starts at the first instant of
the first day of the month and ends on the last instant of the last day of the month, e.g.
2000-04 is equivalent to an interval of [2000-04-01T00:00, 2000-04-30T23:59];

• Note that for a Schedule data type, the specified scheduling details are ignored and only the
outer limits matter. For instance, a schedule that specifies every second day between 31-Jan
2013 and 24-Mar 2013 includes 1-Feb 2013, even though that is on an odd day that is not
specified by the period. This is to keep the server load processing queries reasonable.
As an example, the following query searches for all the encounters over a 2 year period:
GET [base-url]/encounter?date=>2010-01-01&date=<2011-12-31
3.6.2.4 String
The string parameter refers to simple string searches against sequences of characters. Matches are
case insensitive. By default, a match exists if a portion of the parameter value contains the specified
string. It is at the discretion of the server whether to do a left-partial search. The modifier :exact can
be used to indicate that the match needs to be exact (the whole string, including casing and
accents). For example:
GET [base-url]/Patient?name=eve
GET [base-url]/Patient?name:exact=Eve
The first is a request to find any patients with "eve" in any part of the name. This would include
patients with the name "Eve", "Severine", etc. The second search would only return patients with
the name "Eve".
3.6.2.5 Token
A token type is a parameter that searches on a code or identifier value where the value may have a
scope of its meaning.
If the parameter has no modifier, the search is performed against the URI/value from a Coding or an
Identifier. The syntax for the value is one of the following:
• [parameter]=[code] matches a code/value irrespective of its system namespace
• [parameter]=[namespace]|[code] matches a code/value in the given system namespace
4. Resources
Resources within EHR, i.e., instance of data that is stored or exchanged, are divided into groups:
• Administrative,
• Clinical.
4.1 Administrative resources

Administrative resources are used for interactions regarding demographic and other administrative
set of data through the following HL7 documents:
• Patient Registration/Update: It is a HL7 CDA document containing patient identifying and
demographics data with the intent to register of a patient into the EHR or update the associated
administrative/demographical data.

• Healthcare Professional Registration/Update: It is a HL7 FHIR based document containing
healthcare professional identifying and demographics data with the intent register a
healthcare professional into the EHR or update the associated administrative/demographical
data.
Structure and content of these documents is defined in the document "EHR Documentation
Implementation and Validation Guide".
Resource Description
Demographics and other administrative information about a person receiving
Patient
care or other health-related services.
Demographics and qualification information for an individual who is directly
Practitioner
or indirectly involved in the provisioning of healthcare.
Table 8: Administrative resources
4.1.1 Patient
This resource is used for administrative interactions with demographic data of the patient.
Interactions include process of registration patient within EHR, update of the patient demographic
data, change of status and deletion from EHR.
Supported interactions are:
Not implemented: EHR does not return demographic/administrative data of
Search
a patient at this phase of the project.
Create To create a patient record with administrative data in the EHR.
Read
a patient at this phase of the project.
Update To update existing administrative data of a patient in the EHR.
Delete To delete a patient record from the EHR.
Table 9: Patient resource – Supported interactions
4.1.1.1 Create
This interaction is used to register a patient in the EHR. It is initiated by a healthcare institution
where a patient is treated, an Encounter Summary is to be sent and no previous record of the
patient exists in the EHR.
POST /services/patient HTTP/1.1
Host: ehr.eu-ihis.rs
Content-Type: application/hl7-v3+xml
<?xml version="1.0"?>
<ClinicalDocument>

...
</ClinicalDocument>
In case of successful registration, the response is to contain the unique Id assigned to the patient
inside the EHR system.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/patient
To register a patient in the EHR with the demographic/administrative data specified in the body
of the request through the Patient Registration document.
4.1.1.2 Update
This interaction is used to update existing administrative data of a patient in the EHR. Update of
administrative data is possible only for institution responsible for the patient.
PUT /services/patient/[id] HTTP/1.1
<ClinicalDocument>
...
</ClinicalDocument>
The path variable [id] is the identification of the patient. This interaction implies a full update, i.e., all
demographical data of a patient will be updated independently of the specific data that have been
changed.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/patient/1000000555
To update the demographic/administrative data of the patient with EHR id=1000000555 as
specified in the body of the request through the Patient Update document.
4.1.1.3 Delete
This interaction is used to delete a patient record from the EHR. Deletion of patient administrative
data will be available only for authorized institutions and healthcare professionals. Deletion of
administrative data will trigger also deletion of clinical data for patient.
DELETE services/patient/[id] HTTP/1.1
The path variable [id] represents Id of the patient to be deleted from EHR. Deletion operation cannot
be reverted and in case of wrong deletion, the patient must be registered again.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/patient/1000000555
To delete from the EHR the record of the patient with EHR id=1000000555.

4.1.2 Practitioner
Resource is used to support interactions of administrative and specialist data for the healthcare
professional.
Search
a healthcare professional at this phase of the project.
To create a healthcare professional record with administrative data in the
Create
EHR.
Read
a healthcare professional at this phase of the project.
To update existing administrative data of a healthcare professional in the
Update
EHR.
Delete To delete a healthcare professional record from the EHR.
Table 10: Practitioner resource – Supported interactions
4.1.2.1 Create
This interaction is used to register a healthcare professional in the EHR. Creation of the healthcare
professional is initiated by the health institution when a new healthcare professional is registered
inside its system.
POST services/practitioner HTTP/1.1
<Practitioner>
...
</ Practitioner >
In case of successful registration the response is to contain the unique Id assigned to the healthcare
professional inside the EHR system.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/practitioner
To register a healthcare professional in the EHR with the demographic/administrative data
specified in the body of the request through the Healthcare Professional Registration document.
4.1.2.2 Update
This interaction is used to update existing administrative data of a healthcare professional in the
EHR.

PUT services/practitioner/[id] HTTP/1.1
< Practitioner >
...
</ Practitioner >
The path variable [id] is the identification of the healthcare professional. This interaction implies a
full update, i.e., all demographical data of a healthcare professional will be updated independently
of the specific data that have been changed.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/practitioner/1000000888
To update the demographic/administrative data of the patient with EHR id=1000000555 as
specified in the body of the request through the Healthcare Professional Update document.
4.1.2.3 Delete
This interaction is used to delete a healthcare professional record from the EHR. Deletion of
healthcare professional administrative data will be available only for authorized institutions.
DELETE services/practitioner/[id] HTTP/1.1
The path variable [id] represents Id of the healthcare professional to be deleted from the EHR.
Deletion operation cannot be reverted and in case of wrong deletion, the healthcare professional
must be registered again.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/practitioner/1000000888
To delete from the EHR the record of the healthcare professional with EHR id=1000000888.
4.2 Clinical resources

Clinical resources are used for interactions regarding clinical set of data through the following HL7
CDA documents:
• Patient Summary: It is a medical report that documents the actual and previous conditions of
the patient and contains essential information that helps determine an individual's health status
• Encounter Summary: It is a document that is a synopsis of a patient's encounter i.e., ambulatory
or hospitalization.
• Hospitalization Report: It is an individual report of the hospitalization of a patient that forms part
of the statutory medical records of hospitalized patients.
Structure and content of these documents is defined in the document "EHR Documentation
Implementation and Validation Guide".

Resource Description
Resource for handling Encounter Summary documents. CRUD operations are
Encounter
implemented for this resource.
Resource for handling Patient Summary documents. Since Patient Summary
PatientSummary documents are only created and submitted by the EHR to requesting
healthcare providers, only search operation is implemented for this resource.
Resource for handling Hospitalization Reports. CRUD operations are
Hospitalization
Table 11: Clinical resources
4.2.1 Encounter
This resource is used to support the exchange of HL7 CDA Encounter Summary documents e
Interaction to search Encounter Summary documents in the EHR. It returns
Search
the list of documents meeting the search parameter-based criteria specified.
Interaction to send a new Encounter Summary document to the EHR to add
Create related health data to the corresponding patient's record in the EHR
database as well as register and store the document in its original form..
Read Interaction to retrieve a Encounter Summary document from the EHR.
Interaction to send an Encounter Summary document to the EHR to update
related health data of the corresponding patient's record in the EHR
Update
database as well as register the new version of the document. Old version of
the document and related data will be marked as "obsolete".
Interaction to delete an Encounter Summary document from the EHR. This
Delete interaction will delete the specified document and associated health data
from the corresponding patient record in the EHR database.
Table 12: Encounter resource – Supported interactions
4.2.1.1 Search
Supported search queries:
GET services/clinicaldocument/encounter?{parameters}
The response is to contain the the list of documents meeting the search parameter-based criteria, if
any.
Supported search parameters are:

Parameter Description Type Optionality
identifier EHR identifier of a document. token Optional
Patient identifier (JMBG, LBO, or

subject token Optional
other allowed patient identifier)
date Date search parameter. date Optional
Table 13: Encounter resource – Supported search parameters
URL Samples:
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/encounter?date=>=2014-05-02
To get the list of all Encounter Summary documents created since the 5th of May 2014, included.
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/encounter?date=>=2013-05-
05&date=<=2013-06-05
To get the list of all Encounter Summary documents created from the 5th of May until the 5th of
June 2014, both dates included.
• https://ehr.eu-
ihis.rs/ehr/services/clinicaldocument/encounter?subject=2.16.688.1.1.2.1|123456789012
3
To get the list of all Encounter Summary documents of the patient with JMBG=1234567890123.
4.2.1.2 Create
Purpose of this interaction is to send a new Encounter Summary document to the EHR to add related
health data to the corresponding patient's record in the EHR database as well as register and store
the document in its original form. Interaction is defined as:
POST services/clinicaldocument/encounter HTTP/1.1
<ClinicalDocument>
...
</ClinicalDocument>
In case of successful interaction, the response is to contain the EHR Id of the document which can be
used to track the document within the EHR.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/encounter
To register and store in the EHR the Encounter Summary document specified in the body of the
request and to add related health data to the corresponding patient's record.

4.2.1.3 Read
Purpose of this interaction is to retrieve an Encounter Summary document from the EHR. Interaction
is defined as:
GET services/clinicaldocument/encounter/[id] HTTP/1.1
In case of successful interaction, the response is to contain the specified Encounter Summary
document.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/encounter/111222333
To retrieve the Encounter Summary document with EHR Id=11122233.
4.2.1.4 Update
Purpose of this interaction is to register and store a new version of an Encounter Summary
document in the EHR as well as to update related health data from the corresponding patient's
record in the EHR database. This request implies a full update, i.e., partial update of data is not
allowed and it is necessary to send complete new version of the document.
PUT services/clinicaldocument/encounter/[id] HTTP/1.1
<Clinicaldocument>
...
</ClinicalDocument>
The path variable [id] represents Id of the existing document, for which the update is requested.
URL Sample:
To replace the Encounter Summary document with EHR Id= 111222333 with the new version of
the document specified in the body of the request, and to update related health data from the
corresponding patient's record.
4.2.1.5 Delete
Purpose of this interaction is to delete an Encounter Summary document from EHR i.e., to delete the
specified document and associated health data from the corresponding patient record in the EHR
database.
DELETE services/clinicaldocument/encounter/[id]

Only authorized organizations and healthcare professionals will be authorized for deletion of the
document.
URL Sample:
To delete from the EHR the Encounter Summary document with EHR Id=111222333 and
associated health data from the corresponding patient record.
4.2.2 Hospitalization
This resource is used to support HL7 CDA Hospitalization Report documents exchange between
institutions.
Search Interaction for searching existing Hospitalization Reports within EHR.

Interaction to send a new Hospitalization Report to the EHR to be registered
and stored as a document in its original form. Data contained in a
Create Hospitalization Report are not stored in the EHR database since those data
are stored through the Encounter Summary document associated to each
hospitalization.
Read Interaction to retrieve a Hospitalization Report from the EHR.
Interaction to send a Hospitalization Report to the EHR to register and store
Update the new version of the document. Old version of the document will be
marked as "obsolete".
Delete Interaction to delete a Hospitalization Report from the EHR.
Table 14: Hospitalization resource – Supported interactions
4.2.2.1 Search
Purpose of this interaction is to search for existing Hospitalization Reports within EHR based on the
search parameters criteria specified.
GET services/clinicaldocument/hospitalization?{parameters}
The response is to contain the the list of documents meeting the search parameter-based criteria, if
any.
identifier EHR identifier of a document. token Optional
Patient identifier (JMBG, LBO, or

subject token Optional
other allowed patient identifier)

Table 15: Hospitalization resource – Supported search parameters
URL Samples:
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/hospitalization?date=>=2014-05-02
To get the list of all Hospitalization Reports created since 5th of May 2014, included.
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/hospitalization?date=>=2013-05-
05&date=<=2013-06-05
To get the list of all Hospitalization Reports from 5th of May until the 5th June 2014, both dates
included.
• https://ehr.eu-
ihis.rs/ehr/services/clinicaldocument/hospitalization?subject=2.16.688.1.1.2.1|123456789
0123
To get the list of all Search all Hospitalization Reports for the patient with
JMBG=1234567890123.
4.2.2.2 Create
Purpose of this interaction is to send a new Hospitalization Report to the EHR to be registered and
stored in its original form. Interaction is defined as:
POST services/clinicaldocument/hospitalization HTTP/1.1
<ClinicalDocument>
...
</ClinicalDocument>
In case of successful interaction, the response is to contain the EHR Id of the document which can be
used to track the document within the EHR.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/hospitalization
To register and store in the EHR the Hospitalization Report specified in the body of the request.
4.2.2.3 Read
Purpose of this interaction is to retrieve a Hospitalization Report from the EHR. Interaction is defined
as:
GET services/clinicaldocument/hospitalization/[id] HTTP/1.1

In case of successful interaction, the response request is to contain the specified Hospitalization
Report.
URL Sample:
• https://ehr.eu-ihis.rs/ehr/services/clinicaldocument/hospitalization/222333444
To retrieve the Hospitalization Report with EHR Id=222333444.
4.2.2.4 Update
Purpose of this interaction is to register and store a new version of a Hospitalization Report in the
EHR. This request implies a full update, i.e., partial update of data is not allowed and it is necessary
to send complete new version of the document.
PUT services/clinicaldocument/hospitalization/[id] HTTP/1.1
<ClinicalDocument>
...
</ClinicalDocument>
The path variable [id] represents Id of the existing document, for which the update is requested.
URL Sample:
To replace the Hospitalization Report with EHR Id= 222333444 with the new version of the
document specified in the body of the request.
4.2.2.5 Delete
Purpose of this interaction is to delete a Hospitalization Report document from the EHR.
DELETE services/clinicaldocument/hospitalization/[id]
Only authorized organizations and healthcare professionals will be authorized for deletion of the
document.
URL Samples:
To delete the Hospitalization Report with EHR Id=222333444.
4.2.3 Patient Summary

This resource is used to support the search and retrieval of the pertinent data from EHR about
patient through HL7 CDA Patient Summary documents. Since Patient Summary documents are only
created and submitted by the EHR to requesting healthcare providers, only search operation is

Interaction to search and retrieve the Patient Summary document of a
Search
patient.
Table 16: Patient Summary resource – Supported interactions
4.2.3.1 Search
Purpose of this interaction is to search and retrieve the Patient Summary document of a patient.
GET services/clinicaldocument/patientsummary?{parameters}
The response is to contain the Patient Summary document requested based on the search
parameters specified.
Patient identifier (JMBG, LBO, or other allowed patient
subject token Mandatory
identifier)
Table 17: Patient Summary resource – Supported search parameters
URL Samples:
• http://ehr.eu-ihis.rs/ehr/services/clinicaldocument/patientsummary?subject=EE83CE85-
099A-4BFE-8180-BEAC712CEA6A
To search and retrieve the Patient Summary document of the patient with EHR Id= EE83CE85-
099A-4BFE-8180-BEAC712CEA6A.
• https://ehr.eu-
his.rs/ehr/services/clinicaldocument/patientsummary?subject=2.16.688.1.1.2.1|12345678
90123&date=>=2013-05-05&date=<=2013-06-05
To search and retrieve the Patient Summary document of the patient with
JMBG=1234567890123 covering the specified period.


Eu-Ihis Ehr Restful API Final en

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Eu-Ihis Ehr Restful API Final en

Enviado por

Direitos autorais:

Formatos disponíveis

Hospital Health Information System – EU HIS

Contract No. IPA/2012/283-805

EHR RESTful API

This project is funded by Republic of Serbia Implemented by the

CDA Clinical Document Architecture

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

2. RESTFUL PRINCIPLES ................................................................................................................................ 4

2.1 USE HTTP METHODS EXPLICITLY ....................................................................................................... 4

3. EHR RESTFUL API COMMON CONCEPTS................................................................................................... 6

3.1 URL OPERATIONS STYLE GUIDE ......................................................................................................... 6

4.1 ADMINISTRATIVE RESOURCES ............................................................................................................ 13

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Table 1: HTTP status codes .............................................................................................................................. 7

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

2.1 Use HTTP Methods Explicitly

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

2.3 Expose Directory Structure-Like URIs

2.4 Transfer XML, JSON, or Both

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

3. EHR RESTful API Common Concepts

OPERATION [base]/[type]/[id] {?_format=[mime-type]}

• OPERATION – HTTP verb used for operation

3.2 Service Root URL

3.3 HTTP Status Codes

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Code Group Code Type

4XX Client error

5XX Server error

Table 1: HTTP status codes

3.4 Content Types and Encodings

3.5 Resource-Level Interactions

Read Read the current state of the resource.

Create Create new resource.

Update Update the current state of the resource by its Id.

Delete Delete resource by its Id.

Search Search resource type by some searching criteria.

Table 2: Resource level interactions

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Table 3: Read interaction – Common HTTP status codes returned

Table 4: Create interaction – Common HTTP status codes returned

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Table 5: Update interaction – Common HTTP status codes returned

Table 6: Delete interaction – Common HTTP status codes returned

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

To search a single resource type:

3.6 Search / Query

3.6.1 Parameters for each resource

3.6.2 Search parameter types

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Table 7: Search parameters types

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

4.1 Administrative resources

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Table 8: Administrative resources

Table 9: Patient resource – Supported interactions

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Table 10: Practitioner resource – Supported interactions

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

4.2 Clinical resources

IPA/2012/283-805 (EC); 00080065 (UNOPS) EHR RESTful API

Table 11: Clinical resources