API Documentation

Introduction
This document provides an overview of the EHRYourWay Clinical Web API. This API provides access to patient information,
in accordance to the regulations cited by ONC in 170.315 (g)(7) and (9). In the rest of the document, the term “EHRYourWay”
refers to EHR software implemented by EHRYourWay.

The Clinical Web API can be accessed by any patient of EHRYourWay, who provided a consent for external access, of the
clinical information. Upon receiving the consent, the software provides the following information to the patient.

a)      An external patient id.

b)      A Client Id and password for login.

The patient can utilize the above credentials to access the clinical information.

Architecture of the System
A broad overview of the clinical systems architecture is provided below, to help clients interact with the external
Clinical Web API provided by EHR Your Way.


Figure-1: Architecture of EHR Your Way Clinical Web API

API Implementation
The client Interaction with the EHR Your Way Clinical Web API, comprises of three functions.
Please refer to the architecture diagram (figure-1), shown above.

1)      Login to the system via Authentication Server.

2)      Authenticate the login by Web API Server.

3)      Access Clinical data via Web API Request Handler.

 The client interaction with respect to Clinical Web API outlined in ONC 170.315 is as described below.

Sno

API

Functional Requirement

Clinical Web API Function(s)

1

170.315 (g)(7)

The technology must be able to receive a request with sufficient information to uniquely identify a patient and return an ID or other token that can be used by an application to subsequently execute requests for that patient's data.

1)Login to Authentication Server;

2)Authentication by Web API Server

The external patient id, and an access token are returned.

 

2

170.315 (g)(9)

Respond to requests for patient data (based on an ID or other token) for all of the data categories specified in the Common Clinical Data Set at one time and return such data (according to the specified standards, where applicable) in a summary record formatted according to the standard specified in §170.205(a)(4) following the USCDI document template.

Access Clinical data via
Web API Request Handler.

All data categories is passed as parameter.

The output format is passed as parameter.

 

Security
The EHR Your Way Clinical Web API provides robust multi-level security. The users are authenticated during login,
and subsequently every request to the Clinical Web API is authenticated and authorized.

Login Authentication: The EHR Your Way Clinical Web API is singulary focussed to clinical data access by authorized parties,
and as such, does not provide any authentication on its own. Authentication is provided by EHR Your Way Authentication Server,
which is capable of authenticating valid EHR Your Way clients.

Authentication in EHR Your Way Clinical Web API, is as described below.
a) The user logs into the system, with a client id and password using EHRYourWay Authentication Server.
     If the client credentials are valid, the server returns a reference number, which must be consumed
     within a predefined time limit (set as 5 minutes for testing, and 2 minutes in production).

b) The Web API Server authenticates the login, wherein the client Id and reference number provided
     in previous step are accepted as input. If the authentication is successful, the Web API Server
     returns an access token, along with the external patient id.

Request Authentication and Authorization: After login and authentication by the WEB API Server, the client Id, external patent id,
and access token received, can be used for accessing the Clinical Web API.

Every request to the Clinical Web API is subjected to  authentication, wherein the supplied client Id, and access token are revalidated.

After successful authentication, the request is subjected to authorization. Every request to the Clinical Web API must provide
HMAC signature of the headers, and content. Authorization comprises of validating the HMAC signature in the request,
with the computed signature.

Request authorization is a complex process, and the full details are presented in Appendix-2.

Software Components & Configurations
The EHR Your Way Clinical Web API is made available as Web Services, using hypertext transmission protocol (http). The requests and
responses use Json payload, i.e http content-type="text/plain" or "application/json".

The EHR Your Way Clinical Web API can be easily accessed using PostMan©, or any other software tool or application, capable of sending
http requests, and receiving http responses with json payload.

API Syntax
The external agent must construct web requests, and invoke the web API provided by
EHRYourWay as detailed below.

Convention:  In the following, parameters shown in red, are mandatory.

Web API for Client Login:
Method: POST
URL: https://webcpg.ehryourway.com/EHRAuthenticationServer/api/web/ClientLogin

Request:   {
        "ClientId": "Alicejones",
        "Password": "Alicejones123*"
}

Response sent on Successful Authentication
{
    "ClientId": "Alicejones",
    "ReferenceNumber": "5698180926668800",
    "ValidationMessages": null,
    "ValidationStatus": "Success"
}

Response sent when Authentication Fails
{
    "ClientId": " Alicejones ",
    "ValidationMessages": "Client Login Failed",
    "ValidationStatus": "Failed"
}

 

Web API to Authenticate Client Login:
Method: POST
URL: https://webcpg.ehryourway.com/EHRWebAPIServer/api/web/AuthenticateClientLogin

Request:
{
    "ClientId": "Alicejones",
    "ReferenceNumber": "5698180926668800"
}

Response sent on Successful Validation   
{
    "ClientId": "Alicejones",
    "ReferenceNumber": "5698180926668800",
    "ExternalPatientId": "448Alan050119703406",
    "AccessToken": "81196298-0585-4438-9494-64ddd8015cd6",
    "accessTokenExpiryDT": "2018-07-11T02:31:00",
    "ValidationMessages": null,
    "ValidationStatus": "Success"
}

Response sent when Validation Fails
{
    "ClientId": "Alicejones",
    "ReferenceNumber": "56981809266688001",
    "Inner Exception": "Could not locate Access Token",
    "ValidationMessages": "Validation of Reference Number Failed.",
    "ValidationStatus": "Failed"
}

Web API to Get All Patient Clinical data: 

Method: POST
URL: https://webcpg.ehryourway.com//EHRWebAPIRequestHandler/api/web/GetClinicalData 
Request:

{
    "ClientId": "Alicejones",
    "ExternalPatientId": "448Alan050119703406",
    "AccessToken": "81196298-0585-4438-9494-64ddd8015cd6",
    "Sections": [ "all" ],
    "FromDate": "06/22/2014",
    "ToDate": "06/22/2015",        
    "ClinicalDataAccessType": 2
}




Response sent on Successful Retrieval

{
    "PatientUSCDIAsXml": "<ClinicalDocument> ... </ClinicalDocument>",

    "PatientUSCDIAsReadableFormat": "https://webcpg.ehryourway.com/EMR_Web_WCF_ClinicalManagement/temp/a6129221e4f94086a1cfac63b6282adf.xml",
    "JSONFormat": null,
    "ValidationStatus": "Success",
    "ValidationMessages": null
}

Response sent when Retrieval Fails
- - -   same as Web API to Get Clinical Data by Category   - - -


Exceptions and Error Conditions

Exceptions and error conditions are indicated as follows:
1) The http status code not equal to 200 (OK).
                                      - - - OR - - -
2) "ValidationStatus": "Failed" in the json response sent.

Conversely a success is indicated by the following conditions.
1) The http status code is equal to 200 (OK).
                                      - - - AND - - -
2) The response sent should contain "ValidationStatus": "Success".


Appendix-1

The list of Categories used in USCDIS Retrieval.

Category List

Patient Name
Sex
Race
Ethnicity
Preferred Language
Date of Birth
Care Team Member(s)
Smoking Status
Health Concerns
Goals
Assessment
Plan of Treatment
Medication Allergies
Problems
Immunizations
Medications
Results
Vital Signs
Procedures
Implantable Device(s)
Reason For Visit
Encounter
Refer to Consultant(s)
Functional Status
Cognitive Status
History And Physical Exam
Procedure Note
Progress Note
Laboratory Report Narrative
Consultation Note
Discharge Summary Note
Imaging Narrative
Pathology Report Narrative



Appendix-2

Request Generation using HMAC Signatures
The procedure followed for authorizing requests in EHR Your Way Clinical Web API, is based on the IETF draft recommendation for
signing HTTP Messages. This draft is authored by M. Cavage and M. Sporny, and is available at
https://datatracker.ietf.org/doc/draft-cavage-http-signatures/. The current version at the time of this document preparation is
version-10, and expires on Novemebr 15, 2018.

The Http Request generation with HMAC signature is as detailed below.

Step-1: Creation of Signing String.
A signing string is created with the following information. The headers used are compiled from the IETF recommendation cited above.
-----------------------------------------------------Begin---------------------------------------------------------------
(request-target): post /EHRWebAPIRequestHandler/api/web/GetClinicalDataByCategory
host: localhost
date: Thu, 12 Jul 2018 10:50:32 GMT
digest: b5f68208531d3d9fcf1d5886341f04404de64fa4d27770e6112c4cd6dfb050bc
content-length: 692
nonce: a209bf19-defb-4e3f-addb-83f50b2ccdbe
x-authorization-timestamp: 1531412432
-----------------------------------------------------End---------------------------------------------------------------

In the above, digest is the hex string of SHA256 of the httpcontent in UTF-8 format. Nonce is a random uid, and x-authorization-timestamp is Unix time.

Step-2: Sign HMAC-SHA256 Algorithm
The signing string created in step-1 is signed with HMAC-SHA256 algorithm, using hex string of SHA256 of password as key.

Step-3: Creation of Authorization Header
The Authorization header is created as shown below.
-----------------------------------------------------Begin---------------------------------------------------------------
keyId="jdonald",accessToken="36f0140a-1744-4116-a6db-bd1f6fc2e72c",
algorithm="hmac-sha256",nonce="a209bf19-defb-4e3f-addb-83f50b2ccdbe",
headers="(request-target)%20host%20date%20digest%20content-length%20x-authorization-timestamp",
signature="fn6uRwbwq2+bw26Z8ya+SS6lZPSQxZm78iqGoSZcc10="
-----------------------------------------------------End---------------------------------------------------------------

In the above, keyId is the clientId, accessToken is the access token of the clientId, nonce and headers are from step-1, signature is base64 string of
HMAC signature created in step-2.

The http request can be generated as shown below.  The following code is in .NET C#, and can be easily converted to other popular languages and platforms.

//***************************************************************************************
//* Variable definitions                                                                *
//***************************************************************************************
string  url = “https://webcpg.ehryourway.com//EHRWebAPIRequestHandler/api/web/GetClinicalData”;

string strPatientInfoReqJson = “ your request json string “;
string strAuthorizationHeader = “ copy authorization header from step-3 above”;
DateTime hdrDate = DateTime.Now(); 
string  strHost = “webcpg.ehryourway.com”;
string  strDigest = “SHA256 of the content i.e the request json string”;
string  strXAuthTS = “unix time in string format”;
     //***************************************************************************************
//* Build request                                                                       *
//***************************************************************************************

// create request
httpRequestMessage = new HttpRequestMessage(HttpMethod.Post, "");          

// set uri

httpRequestMessage.RequestUri = new Uri(url);

 

// set content

httpRequestContent = new StringContent(strPatientInfoReqJson,
                                                   Encoding.UTF8, "text/json");

httpRequestMessage.Content = httpRequestContent;

               

// set Authorization header

httpRequestMessage.Headers.Authorization =
                 new AuthenticationHeaderValue("Signature", strAuthorizationHeader);

 

// set date

httpRequestMessage.Headers.Date = hdrdate;

 

// set host

httpRequestMessage.Headers.Host = strHost;

 

// set digest

httpRequestMessage.Headers.Add("digest", strDigest);

 

// set Authentication Timestamp

httpRequestMessage.Headers.Add("X-Authorization-Timestamp", strXAuthTS);

// send request to web server

HttpResponseMessage response =
    await myClient.SendAsync(httpRequestMessage).ConfigureAwait(false);