REST API

Getting Started

The Delivery REST API allows you to interact with Healthwise content using the standard REST internet protocol. This API has predictable, resource oriented, GET URLs. It returns either JSON-encoded responses or renditions of the requested media type.

Before You Begin

This guide assumes you have a working knowledge of the Compass data model. If you are new, we recommend you review the data model reference before continuing. See the Data Model section for more information.

Authentication

The Delivery REST API uses bearer token authentication. An embed code might also be used as a query parameter for authentication when embedding calls within a website. See Authentication to learn how to get a token or embed code.

If using a bearer token, authentication in the the content service by providing the token as a bearer token:

curl -i -X GET "https://delivery.healthwise.net/api/v1/content" -H "Authorization: Bearer YourAccessTokenHere"

If using an embed code, provide the embed code as a query parameter when embedding calls within a website:

https://delivery.healthwise.net/api/v1/content?ecode=YourEmbedCodeHere

Core Functionality

Content Inventory

This is a paginated list of content resources. You can narrow the inventory by specifying a content ID, a core set ID, or by providing filters. To paginate through the response, supply top and skip query parameters.

Examples

Request the titles for all content associated with the Asthma concept:

https://delivery.healthwise.net/api/v1/content?retrieve=title&concept=hwcv_20425

Request the core set data for the content associated with the Abscessed Tooth core content set:

https://delivery.healthwise.net/api/v1/content/cc_00004?retrieve=coresets

Request all the content data for the What Is aspect of the Abscessed Tooth core set:

https://delivery.healthwise.net/api/v1/content/cc_00004/whatis?retrieve=*

Request the content record for the topic abo2094:

https://delivery.healthwise.net/api/v1/content/abo2094

Content Rendition

This is a single piece of content rendered as JSON or HTML. You can navigate to the content in the following ways:

• By its ID, localization, and format.
• Semantically by its core set, aspect, localization, and format.

Examples

Request the HTML-formatted, American-English rendition of topic abo2094:

https://delivery.healthwise.net/api/v1/content/abo2094/en-us/html

Request the longest available JSON-formatted, American-English rendition of the What Is aspect of the Abscessed Tooth core set:

https://delivery.healthwise.net/api/v1/content/cc_00004/whatis/en-us/json

Core Content Sets Inventory

This is a paginated list of resources for our core content sets. You can narrow the inventory by navigating to a specific core set or by providing filters. To paginate through the response, supply top and skip query parameters.

Examples

Request the aspect and title for all core set records associated with the SNOMED CT code 309081009-Abnormal Cervical Smear:

https://delivery.healthwise.net/api/v1/coreset?retrieve=title,aspects&snomed=309081009

Request all the data for the Grief core set CC_00290:

https://delivery.healthwise.net/api/v1/coreset/cc_00290?retrieve=*

Static Resource

Static resources, such as disclaimers, can be requested individually by the resource type, localization, and format.

Examples

Request the HTML-formatted, American-English Healthwise disclaimer:

https://delivery.healthwise.net/api/v1/resource/healthwiseDisclaimer/en-us/html

Errors

The Delivery REST API uses standard HTTP response codes to indicate the success or failure of a request.

In general, each code will have a corresponding meaning:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed due to information given the request.
• Codes in the 5xx range indicate an error with the servers at Healthwise (these are rare).

Code Number	Response	Response Description
200	OK	Everything worked as expected.
400	Bad Request	The requested was invalid, often due to incorrect query parameters.
401	Unauthorized	No valid API key was provided.
403	Forbidden	The API key does not have permissions to perform the request or does not have permissions to access the requested content.
404	Not Found	The requested resource was not found. There are several reasons why this might occur. See the following Interpreting a 404 Response section.
500, 502, 503, 504	Server Error	Something went wrong on the Healthwise server.

Interpreting a 404 Response

When the API returns a 404-status code it means that the requested resource was not found. The reason this occurs is because the 404 HTTP response contains a JSON object with Code and Message properties. Program off the provided code to handle each scenario appropriately in your application.

Code	Description
intentional_gap	The requested resource is an intentional gap.
no_results	No results were found for the given query.
nonexistent	No resource was found for the provided ID.

Example 404 Response Body

{
    "code": "intentional_gap",
    "message": "We do not have content about this concept and aspect."
}

Versioning

The Delivery REST API uses URI versioning to manage changes and improvements. The version must be indicated in the URI that uses a whole number incrementing pattern.

• When backwards-incompatible changes are made, a new version will be released.
• When backwards-compatible changes are made, meaning they will not impact your current integration, we incorporate these changes into this existing version.

Usage Tracking

When making API calls, you can include a brief description about why you are making the API call. Filling out this information is optional; however, it helps us understand your use cases and assists in troubleshooting any issues that might come up.

To specify usage tracking for the REST API, provide your description in the HW-Client-Purpose header parameter.