NICE Syndication Services Help

Intended audience

This document is aimed at content integrators, widget builders and application developers who wish to integrate content from the National Institute for Health and Care Excellence into their own applications.

About the NICE Syndication Services API

The NICE Syndication Services API has been implemented as a REST service. While there are many, equally valid, ways of making resources available across the web we have chosen REST because it is built on a technology that is supported by the broadest range of platforms, languages and frameworks: HTTP. For more information about REST please see the resources listed below:

How to Sign Up

  1. Register using Evidence Search.
  2. Go to your account page and agree to the terms and conditions of use for NICE Syndication Services.
  3. Request access to the services that you are interested in accessing.

Discovering Resources

The easiest way to find out what resources NICE Syndication Services has available is to use a web browser. Simply start at the top-level of the service and follow the links to the desired resource.

Where a resource is available in multiple formats ('representations' in the idiom of REST) a link to each format will be displayed at the top of the page. The media type of the response has been specified by suffixing the URI with the appropriate file extension: ".json" for application/json, ".xml" for application/xml, and so on. This file extension support has been implemented primarily for the convenience of being able to provide a links to different representations from a web page. The preferred method of content negotiation is by adding HTTP Accept header to the request identifying the desired media type.

Media type links for a resource

The HTML representation of a resource only shows a subset of the available data, to see all the properties of a resources simply select one of the representations intended for consumption in code (e.g. JsON or XML).

Identifying resource types

Most of the resources that can be found in the API contain links to other related resources. In order to identify what type of resource is being linked to, all links include a "rel" or "relationship" attribute, and idea that has been borrowed from the Atom specification.

In the snippet from the Guidance resource below you can see five linked resources, the first, "self", gives the URI of the current resource. The remaining four identify other resource types from the Guidance hierarchy.

<Guidance xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Title>Guidance</Title>
  <Links>
    <Link rel="self" uri="https://api.nice.org.uk/services/guidance" title="Guidance" />
    <Link rel="/linkrels/guidance/by-date/helper" uri="https://api.nice.org.uk/services/guidance/by-date" title="Guidance By Date" />
    <Link rel="/linkrels/guidance/index" uri="https://api.nice.org.uk/services/guidance/index" title="Guidance Index" />
    <Link rel="/linkrels/guidance/programmes" uri="https://api.nice.org.uk/services/guidance/programmes" title="Guidance Programmes" />
    <Link rel="/linkrels/guidance/taxonomy" uri="https://api.nice.org.uk/services/guidance/taxonomy" title="Taxonomy" />
  </Links>
</Guidance> 

A complete list of the relationship types used within the NICE Syndication Services API can be found on the link relationships page.

Making Requests

In order to access NICE Syndication Services from code (as opposed to this website) you will need to add two headers to your HTTP request:

  • API-Key with your API key as the associated value (this can be found on your account and also embedded into the code samples in HTML view of every resource).
  • Accept with the value set to the desired media type(s) (media type quality is supported).

To determine the current state of a resource and to help minimise the amount of data transferred between your application and the Synidcation Service we support ETAGS, Last-modified headers and HEAD requests.

Response Codes

The response codes issued by the Syndication Service and possible reasons for them are shown below:

  • 200 OK - the request was processed successfully.
  • 304 Not Modified - the resource has not changed since the date specified in the request's If-Modified-Since header, or the ETAG matches the value of the request's If-None-Match header.
  • 400 Bad Request - as well as being issued when a request is malformed request, this will also be sent when a query string parameter or parameterised URI segment is in an unexpected format or out of range.
  • 401 Unauthorized - the API key was either not sent in the request, not recognized or was recognized but is not currently active.
  • 403 Forbidden - the API key was recognized but doesn't allow you to access the requested resource.
  • 404 Not Found - the requested URI doesn't exist within the Syndication Service or the resource identified by the URI is not present.
  • 406 Not Acceptable - the media type requested is not available for this resource.
  • 410 Gone - the resource is no longer available
  • 500 Internal Server Error - the server encountered an error while trying to process the request.

Versioning of resources

We may occasionally find it necessary to change some of the properties of our resources, from the perpective of the API these changes fall into two broad categories: breaking and non-breaking. A non-breaking change might be something such as the addition of a property to a resource or a change in the way a particular value is formatted. Broadly speaking these are changes which we consider unlikely to adversly effect the processing of the resource by the consumers of the API. By contrast, a breaking change is one which may cause errors in programs consuming the API such as the removal or renaming of a property, or the changing a property from a simple field to an array.

In order to minimise the impact that changes in the API have on consuming code, we have implemented a mechanism that makes it possible to specify which version of a resource is returned from a request. This is achieved by adding the version number as a media type parameter in the Accept header. For example:

Accept: application/vnd.nice.syndication.guidance+json;version=1.0

  • Requesting a resource without a version number will result in the most recent version of the resource being returned
  • Requesting a version of a resource that does not exist will result in a Not Acceptable response (status code 406)
  • Requesting a version of a resource that has been deprecated will result in the most recent version of the resource being returned

Using the API to build a widget

The files below contain an example of a javascript widget the use the Syndication Services API to perform a search on Evidence Search.

The reponsibilites of the 'bootstrapper' are to ensure that widget's dependencies are loaded (jQuery in this case), to create the widget's styling and html elements, and then to load the main widget code.

The widget code in divided into main modules: a namespacing helper, the search functionality, and the user-interface code.

To embed the widget in a page, simply add the script element below at the point where the widget is to be rendered.

<script type="text/javascript" 
        src="/content/widget/bootstrapper.js">
        data-nice-api-key="[Your API key here]"></script>