info@ehryourway.com | 877.478.7773

Clinical API

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

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

  1. An external patient id.
  2. 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.

image001

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)(8)

Respond to requests for patient data (based on an ID or other token) for each of the individual data categories specified in the Common Clinical Data Set and return the full set of data for that data category (according to the specified standards, where applicable) in a computable format.

Access Clinical data via
Web API Request Handler.

The individual data categories, and output format, are passed as parameters.

The clinical data of the requested categories is returned in Json format.

3

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 CCD document template.

Access Clinical data via
Web API Request Handler.

All data categories, and output format, ares 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 Clinical Data by Category:

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

Request:
{
    “ClientId”: “Alicejones”,
    “ExternalPatientId”: “448Alan050119703406”,
    “AccessToken”: “81196298-0585-4438-9494-64ddd8015cd6“,
    “Sections”: [ “Patient name” ],
    “FromDate”: “06/22/2014”,
     “ToDate”: “06/22/2015”,      
    “ClinicalDataAccessType”: 1
}

Response sent on Successful Retrieval
{
    “JSONFormat”: {
        “PatientInfo”: [
            {
                “LastName”: “Newman”,
                “FirstName”: “Alice”,
                “MiddleName”: “Jones”,
                “Prefix”: “Ms.”,
                “Suffix”: “”
            }
        ]
    },
    “ValidationStatus”: “Success”,
    “ValidationMessages”: null
}
 

Response sent when Retrieval Fails
{
    “ClientId”: “Alicejones”,
    “AccessToken”: “81196298-0585-4438-9494-64ddd8015cd6*”,
    “ExternalPatientId”: “448Alan050119703406”,
    “Inner Exception”: “Invalid Access Token”,
    “ValidationMessages”: “* Authentication of Request Failed *”,
    “ValidationStatus”: “Failed”
}



{
    “ClientId”: “Alicejones”,
    “AccessToken”: “81196298-0585-4438-9494-64ddd8015cd6“,
    “ExternalPatientId”: “448Alan050119703406*”,
    “Inner Exception”: “Could not locate External Patient Id”,
    “ValidationMessages”: “* UnAuthorized Request *”,
    “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
{
    “PatientCCDAAsXml”: “<ClinicalDocument> … </ClinicalDocument>”,
    “PatientCCDAAsReadableFormat”: “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 CCDS 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)

 

 

 

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//EHRWebAPIServer/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);

 

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

//================================================================================
// This portion of the code is typically held in a static block. The code shown here is merely for completeness. The implementor is adviced to follow the platform and language guidelines. //———————————————————————————————————————————–

// create http client
myClient = new HttpClient();

// set accept header
myClient.DefaultRequestHeaders.Accept.Add( new MediaTypeWithQualityHeaderValue(“application/json”)); //ACCEPT header
//================================================================================

 

// send request to web server

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

 

Terms & Conditions