Health Manager API Documentation

From Dossia Wiki

Jump to: navigation, search

Contents

Introduction

Welcome to the Dossia Application Programming Interface (API). Using the Dossia API, Personal Health Applications (PHAs) can securely read an individual's health record, add new records, provide annotations, upload images and perform other operations to maintain a person's lifelong health record. Dossia's API provides an open interface for it's ecosystem partners to build innovative personal health applications that are focused on the needs of the healthcare consumer.

Terminology

  • A Record pertains to an individual Dossia participant, or user.
  • A record is composed of a set Documents.
  • Documents can be stored hierarchically in a tree structure by specifying a parent document.
  • Dossia uses oAuth as its authentication protocol for all API operations.
  • The Dossia API utilizes a Representational State Transfer (REST) style of software architecture.
  • A Share is created when a user grants access to an application.
  • Shares are based on a collection of Roles.
  • A Role will grant read/write access to specific Document types.

Authentication

  • All API calls are authenticated with OAuth. Further information about the Dossia authentication process and OAuth implementation can be found in the Dossia OAuth Developer Guide.
  • When establishing OAuth authentication the user will always be asked to authenticate with their username and password if they are not already logged in and will be asked to confirm a share/access agreement.
  • A user can revoke access to a share from the Dossia web site.

General Design

  • The Dossia API conforms to the design principles of Representational State Transfer.
  • Dossia currently supports XML, JPEG, PNG and PDF formats in API calls.
  • Data for REST calls should be set in the HTTP body along with matching MIME content type in HTTP headers.
Currently supported MIME content types:
  • application/xml
  • application/pdf
  • image/jpeg
  • image/gif
  • image/bmp
  • image/png

HTTP Status Codes

The Dossia API returns appropriate HTTP status codes for every request:

  • 200 OK: Success
  • 304 Not Modified: There was no new data to return.
  • 400 Bad Request: Your request failed.
  • 401 Not Authorized: Authentication credentials, or the credentials provided are not valid.
  • 403 Forbidden: We understand your request, but are refusing to fulfill it. An accompanying error message should explain why.
  • 404 Not Found: Either an invalid URI has been requested or the resource in question does not exist.
  • 405 Method Not Allowed: A request is initiated with an incorrect HTTP method than that specified in the documentation.
  • 500 Internal Server Error
  • 502 Bad Gateway: Returned if Dossia API is down or being upgraded.
  • 503 Service Unavailable: Dossia's servers are up, but are overloaded with requests. Try again later.

Encoding

  • The Dossia API supports UTF-8 encoding.

API Usage Guidelines

In order to keep the Dossia API running smoothly, please adhere to the following guidelines:

  • If your application does not keep local state, request only the first page of information that you need, and load additional pages only when triggered by user interaction. Use the page parameter.
  • If your application keeps a local archive that persists between sessions, please request documents in batches of 50. Save it locally and avoid requesting it again. Please then behave as above, making use of the query xml inclusions/fromdate to request only documents you haven't seen before

Registering Your Application

Before using the Dossia API, you must:

Dossia API URL Endpoints

The following URL endpoints are available from Dossia for development, staging and production environments.

Development 

 https://dev-api.dossia.org/dossia-restful-api/services/v3.0

Staging 

 https://staging-api.dossia.org/dossia-restful-api/services/v3.0

Production 

 https://api.dossia.org/dossia-restful-api/services/v3.0

Shares and Roles

Dossia embraces the ability to share medical data between individuals and applications. Sharing of data is role-based. Shares may have different roles. Each document type will have an associated role that may be applied. The combination of these roles across document types defines a share type. To prevent user complexity we have predefined a number of share types. Each Personal Health Application will be assigned a share type.

General Guidelines

Dossia offers a number of ways to access and create data. The following guidelines are helpful in understanding the general operation of the API.

  • Documents may be requested individually or part of a group. It should be noted that non-XML documents (e.g. binary documents) cannot be downloaded as part of a group, and must be downloaded individually.
  • XML Data loaded into a participant's record will be validated against known Dossia XML schemas. Please see our Dossia Schema Documentation for more information. Please note that Dossia has provisioned for versioning of the API and our schemas so care should be taken with namespaces.
  • All non-XML data must be attached to an XML document. Non-XML data has to be attached to an XML document by using the Related Documents function when initially uploading the document. This ensures that each non-XML document has meaning. For example, if an API client uploads a scanned image of an immunizaion, the API client should also place a XML document of type Immunization in the participant's record and relate the two documents using the Related Documents function.
  • Relationships between documents are validated as to which document types can be related to other documents. As an example we wouldn't allow an image to be attached to an Encounter document, however we would allow an image to be attached to a Diagnosis. (Not Implemented) Today, the rules for document relationships are not enforced by the API, however they will be in a future release and documented here.
  • All XML documents, whether being sent or received will be wrapped in an XML Container document.
  • When receiving related documents as part of the container non-XML documents will be referred to within a NonXmlDocument document type.
  • Dossia never deletes documents and the API does not expose a method for deleting documents. A document can be annotated or supressed but never deleted.
  • When updating documents we do not remove the documents, we simply version it. The replacement document must be of the same type otherwise an error will occur.
  • Document hierarchies are based upon the most recent version of documents rather than version of the document itself. This allows us to have a consistent way of maintaining relationships between documents.
  • All API calls to obtain a participant's medical documents use a Record ID. The Record ID will always be the first record returned when making a request for available records.
  • Most of our API call results can be modified by specifying query parameters in the request URL. See the Parameterssection for more information.

TimeZone in API documents

In future releases(Dossia 3.0),timezones will be taken into consideration when displaying records entered through the API.Namely the Dossia user will be able to control the timezone that a record is displayed in.The following rules will apply to documents submitted through the API.

  • When no time is included in the document,record will be displayed with only date.If editable,time cannot be added to this record.
  • When time and no timezone is included in the document,record will be displayed with date and time and no timezone. If editable,no timezone will be selected and can be added.
  • Sorting precedence will be in the following order : Date only;Date plus time only,Date plus time plus timezone.
  • User will have a choice to either display in the timezone it was entered with,or to display in a selected timezone.Only records that have entered a timezone will be converted for display when user elects to.
  • API will accept all timezones valid or invalid as part of the document.But only US timezones excluding Arizona will be available for display on the Dossia record.Other timezones will be made available in future releases.


Retrieval of Documents

Parameters

When retrieving documents the behavior can be modified by adding query parameters to the URL.

  • offset - Specifies the offset into the collection of results to start sending documents back
  • limit - Specifies the maximum number of documents to return
  • modfied_since - filter results by only sending documents modified since date. Accepted formats are MMddyyyy/MMddyyyyhh:mm/MMddyyyyhh:mm:ss:SS
  • modified_before - filter results by only send documents modified before date. Accepted formats are MMddyyyy/MMddyyyyhh:mm/MMddyyyyhh:mm:ss:SS
  • hd_start_date_since - filter results by only documents whose health data started since date. Accepted formats are MMddyyyy/MMddyyyyhh:mm/MMddyyyyhh:mm:ss:SS
  • hd_start_date_before - filter results by only documents whose health data started before date. Accepted formats are MMddyyyy/MMddyyyyhh:mm/MMddyyyyhh:mm:ss:SS
  • hd_end_date_since - filter results by only documents whose health data end date is since date. Accepted formats are MMddyyyy/MMddyyyyhh:mm/MMddyyyyhh:mm:ss:SS
  • hd_end_date_before - filter results by only documents whose health data end date is before date. Accepted formats are MMddyyyy/MMddyyyyhh:mm/MMddyyyyhh:mm:ss:SS
  • related_documents - return a documents hierarchy of documents
  • expand_codes_short - requests the server to append the short description of a code where able
  • expand_codes_long - requests the server to append the long description of a code where able
  • ids_only - requests the return Document IDs rather than the full XML document
  • meta - requests the return Document to contain metadata
  • includeFilter - filter to specify documents to include in search. Currently supports filtering by Coding System and Codes. Codes are optional. Format is: codingSystem1:code1,code2,|codingSystem2,code1,code2
  • excludeFilter - filter to specify documents to exclude from search. Currently supports filtering by Coding System and Codes. Unlike includeFilter, excludeFilter does not allow multiple coding system to be passed. Include and Exclude filters may not be used together. Codes are optional. Format is: codingSystem1:code1,code2

Available Records

This function is intended to assist with user shares. If a Dossia participant has access to other users they will be listed here.

Http Method GET
Content-type application/xml
URI {dossia-api-endpoint}/records
Output Container, with document payload of Participant records with first containing the record of the caller.
Allowed Params offset , limit, ids_only
Http Return Codes 200, 401, 404
API Version Compatibility V2.0, V3.0

Sample Output 


<?xml version="1.0" encoding="UTF-8"?>
<api:container xmlns:api="http://www.dossia.org/v2.0/api"
    xmlns="http://www.dossia.org/v2.0/xml/phr" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.dossia.org/v2.0/api http://www.dossia.org/v2.0/api/container.xsd">
    <api:document id="t0FhmOk46GXiarC9VkEcmJSzykB9xH3L">
        <api:payload>
            <Participant type="Primary">
                <FullName>Lovina L Torres</FullName>
                <FirstName>Lovina</FirstName>
                <MiddleName>L</MiddleName>
                <LastName>Torres</LastName>
                <Gender>Male</Gender>
                <Address>
                    <StreetAddress1>842 OKLAHOMA CITY ct</StreetAddress1>
                    <StreetAddress2>unit 977</StreetAddress2>
                    <City>PENN YAN</City>
                    <State>NY</State>
                    <PostalCode>14527</PostalCode>
                </Address>
                <Contact type="Email">lovina.torres@gmail.org</Contact>
            </Participant>
        </api:payload>
    </api:document>
</api:container>

Java Sample Code: 

String call = "{dossia-api-endpoint}/records/";    //Dossia API call.
String httpMethod = "GET";


/*Initialize with the Dossia OAuth URL end-points as shown in Java sample code snippet of 
“New XML Document” Dossia API call.*/

/*Initialize the key and secret with Dossia supplied key and Dossia generated secret respectively 
as shown in Java sample code snippet of “New XML Document” Dossia API call.*/

/*Get the tokens from Dossia OAuth server and initialize the access token and token secret 
as shown in Java sample code snippet of “New XML Document” Dossia API call.*/

/*Create the accessor object and assign the tokens as shown in Java sample code snippet of 
“New XML Document” Dossia API call.*/
        

OAuthClient client = new OAuthClient(new HttpClient3());
OAuthMessage response = client.invoke(accessor, httpMethod,  call, new ArrayList<Map.Entry>());//Make 
Dossia API call
System.out.println(new String(response.readBodyAsString()));//Get reponse text.

C# Sample Code: 

//Parameters declared
Uri uri = null;
OAuthBase oAuth = null;
WebRequest request = null;
string Errormessage = string.Empty;

/* Use Region ‘Parameters’ as explained in ‘New XML Document’ Call  */
/* Use Region ‘oAuth end-point representation values, and some of the Ids’
as explained in ‘New XML Document’ Call  */

//Prepare the URL to be posted
apiPostUrl = OauthConst.DOSSIA_API_URL + "records";

/* Use Region ‘Uri Instantiated and oAuth Library Instance Instantiated’
as explained in ‘New XML Document’ Call  */

//Calling GenerateSignature BaseLibrary Method
signature = oAuth.GenerateSignature(uri, OauthConst.OATH_CONSUMERKEY, 
                            OauthConst.OATH_CONSUMER_SECRET, OauthConst.Token, 
                            OauthConst.TokenSecret, OauthConst.Method_GET, sTimeStamp, 
                            sNonce, OAuthBase.SignatureTypes.HMACSHA1,
                            out sNormalizedUrl, out outParameters);

signature = HttpUtility.UrlEncode(signature); //HTML Enocoding 

/* Use Region ‘Add oAuth QueryString Parameters’
as explained in ‘New XML Document’ Call  */

//Fire HTTP_WEB_REQUEST 
request = HttpWebRequest.Create(sStringb.ToString());
request.Timeout = 600000;
response = (HttpWebResponse)request.GetResponse();

if (response.StatusCode == HttpStatusCode.OK)
{   //SUCCESSFULL CALL
    using (Stream stream = response.GetResponseStream())
    {
        //READ the OUT PUT OF THE CALL 
        StreamReader reader = new StreamReader(stream);
        responseText = reader.ReadToEnd(); //responseText holds OUTPUT

        //Custom Action for the recieved xml output here.
        //As sample: the recieved XML output is written Console.
        //Console.WriteLine(responseText); 
    }
}
else
{
    //Error Occured - Form the Error Message Based on the returned 'StatusCode'
    Errormessage = String.Format("Http Request GET failed. Received HTTP Status Code: {0}", 
                            response.StatusCode);
}

PHP Sample Code: 

<?php
/*Initialize dossia client as shown in PHP sample code snippet of “New XML Document” DossiaAPI call.*/

/*Initialize with the Dossia OAuth URL end-points as shown in PHP sample code snippet of 
“New XML Document” Dossia API call.*/

/*Initialize the key and secret with Dossia supplied key and Dossia generated secret respectively 
as shown in PHP sample code snippet of “New XML Document” Dossia API call.*/

/*Get the tokens from Dossia OAuth server and initialize the access token and token secret 
as shown in PHP sample code snippet of “New XML Document” Dossia API call.*/

/*Initialize API call */
$api_service = "records/";
$test_token = new OAuthConsumer($dossia->token, $dossia->token_secret);
$sig_method = $dossia->hmac_method;
if ($dossia->user_sig_method) $sig_method = $dossia->sig_methods[$dossia->user_sig_method];
$data_req = OAuthRequest::from_consumer_and_token($dossia->the_consumer, $test_token, "GET",
                                                     $dossia->service_path . $api_service, array());
$data_req->sign_request($sig_method, $dossia->the_consumer, $test_token);        
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $data_req);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: OAuth " . implode(",",
                                                                     $data_req->get_parameters())));
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 60);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);    
$output = curl_exec($ch);
curl_close($ch);


Http Method GET
Content-type application/xml
URI {dossia-api-endpoint}/records/v3.0/records/{recordId}/calendarv3.0/records/{recordId}/calendar
Output All Calendars the user has access to.
Allowed Params offset , limit, ids_only
Http Return Codes 200, 401, 404
API Version Compatibility V2.0, V3.0
Http Method GET
Content-type application/xml
URI {dossia-api-endpoint}/records/v3.0/records/{recordId}/calendarv3.0/records/{recordId}/calendar
Output All Calendars the user has access to.
Allowed Params offset , limit, ids_only
Http Return Codes 200, 401, 404
API Version Compatibility V2.0, V3.0
Http Method GET
Content-type application/xml
URI {dossia-api-endpoint}/records/v3.0/records/{recordId}/calendarv3.0/records/{recordId}/calendar
Output All Calendars the user has access to.
Allowed Params offset , limit, ids_only
Http Return Codes 200, 401, 404
API Version Compatibility V2.0, V3.0
Retrieved from "http://docs.dossia.org/index.php/Health_Manager_API_Documentation"
Personal tools