Corporate document

Using your API key to explore NICE content

Using your API key to explore NICE content

The easiest way to find out what resources are available in the NICE syndication service is to use a web browser. Start at the top level of the service and follow the links to your desired resource.

If a resource is available in multiple formats (or 'representations'), each format will be linked at the top of the page. The media type of the response has been specified with the appropriate file extension to the URI: '.json' for application/json, '.xml' for application/xml, and so on. This file extension support makes it easier to link to different representations from a web page. The preferred method of content negotiation is to add an HTTP accept header (see MDN web docs' references section on HTTP accept headers) to the request, identifying the desired media type.

Identifying resource types

Most of the resources in the API link to other related resources. To identify the type of resource, all links include a rel (or 'relationship') attribute – an idea borrowed from the Atom specification.

In box 3, you can see 5 linked resources: the first, self, gives the URI of the current resource. The remaining 4 identify other resource types from the guidance hierarchy.

Box 3 Extract from the guidance resource xml

<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>

See the link relationships page for a complete list of relationship types used in the NICE syndication service API.

Making requests

To access the NICE syndication service from code (as opposed to our website), you will need to add 2 headers to your HTTP request:

  • API-Key, with your API key as the associated value (this can be found on your account and is also embedded into the code samples in the HTML view of every resource).

  • Accept, with the value set to the desired media types.

To determine the current state of a resource and help minimise data transfer between your application and the syndication service, we support ETag (or 'entity tag'), Last-Modified headers and HEAD requests (see MDN web docs' references section on ETag, Last-Modified and HEAD).

Response codes

The response codes issued by the syndication service are explained 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 (see MDN web docs' references section on If-Modified-Since and If-None-Match).

  • 400 Bad Request – the request is malformed or 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 recognised or was recognised but is not currently active.

  • 403 Forbidden – the API key was recognised but doesn't grant access to 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.