API Migration Guide - Microsoft...The following guide will help you migrate from our v1 API to the new Content API. If you want your NHS Choices API integration to continue working

Copyright © 2017 Health and Social Care Information Centre. The Health and Social Care Information Centre is a non-departmental body created by statute, also known as NHS Digital.

Last updated: October 2017

API Migration Guide Migrating from v1.syndication.nhschoices.nhs.uk (v1) to api.nhs.uk (Content API)

API Migration Guide

Copyright © 2017 Health and Social Care Information Centre. 2

Contents Introduction 3

Migration checklist for developers 3

Authentication and headers 3

Endpoints: v1 → Content API mapping 3

Behind the Headlines endpoints 4

Conditions endpoints 4

Content API Query Parameters 5

Behind the Headlines parameters 5

Conditions parameters 5

Content API definitions 6

Behind the Headlines definitions 6

Conditions definitions 8

Error codes 10

Example responses 10

Behind the Headlines 200 response 10

Conditions 202 response 14

Widgets 18

API Migration Guide


Introduction

The following guide will help you migrate from our v1 API to the new Content API. If you want your NHS Choices API integration to continue working after v1 is retired, you must fully migrate it to the Content API. Any new functionality added to the NHS Choices platform will only be added to the Content API.

Migration checklist for developers

Register for an account at https://developer.api.nhs.uk

Subscribe to the All products (trial subscription) at https://developer.api.nhs.uk/products

Familiarise yourself with the new Content API syntax. Look through our API developer portal (https://developer.api.nhs.uk/docs/services) where you can try test-drive Content API calls.

Figure out which v1 endpoints your app uses, and look up the equivalent ones in the Content API using the sections below.

Update your app's code, replacing v1 calls with the Content API calls.

If there's functionality missing in the Content API, update what you can and please contact us about the missing functionality, so we can keep track of feature requests.

The use of the tracking pixel is mandatory and will need to be included on all instances, failure to do so could result in the removal of your subscription.

Once you have modified and tested your code to work with the Content API, subscribe to the products you intend to use and a subscription key will be assigned to you once approved.

Authentication and headers

To make a REST API call, you must include request headers including the Subscription-Key header with a subscription key. All subscriptions under the Content API are available in JSON and XML and you can select your preference under the Accept header. If you do not choose an Accept header then the default output will be JSON.

Endpoints: v1 → Content API mapping

The endpoints for the Content API have now changed and you can see how they have changed in the table below. All v1 endpoints are listed in the left column, and the equivalent Content API endpoints are in the right column.

Header Key Header Value

subscription-key You can view your subscription keys at: https://developer.api.nhs.uk/developer

Accept application/json

application/xml

https://developer.api.nhs.uk/

https://developer.api.nhs.uk/products

https://developer.api.nhs.uk/docs/services

https://developer.api.nhs.uk/developer

API Migration Guide


Behind the Headlines endpoints

Conditions endpoints

The Content API uses the same URL structure as the front-facing website. To view the API replace ‘www’ with ‘api’ in the NHS Choices URL. For example, to get to the news listing page at http://www.nhs.uk/news you would call api.nhs.uk/news.

Method V1 Path (v1.syndication.nhschoices.nhs.uk)

Content API Path (api.nhs.uk)

All articles GET /bth/articles/all /news

Articles by date

GET /bth/articles/{Year}/{Month} Example: /bth/articles/2017/january

/news/?startDate={YYYY-MM-DD}&endDate={YYYY-MM-DD} Example: /news/?startDate=2017-01-01&endDate=2017-01-31

Articles since

GET /bth/articlessince/{Year}/{Month}/{Day} Example: bth/articlessince/2017/1/1

/news/?startDate={YYYY-MM-DD} Example: /news/?startDate=2017-01-01

Categories GET /bth/categories/{Category} Example: bth/categories/Diabetes

/news/{Category} Example: /news/diabetes

Article GET /bth/articles/{Year}/{Month}/{ArticleURL} Example: /bth/articles/2017/august/reports-that-women-have-more-stamina-look-a-little-weak

/news/{Category}/{ArticleURL} Example: /news/lifestyle-and-exercise/reports-women-have-more-stamina-look-little-weak

Method

V1 Path (v1.syndication.nhschoices.nhs.uk)

Content API Path (api.nhs.uk)

All articles

GET /conditions/atoz/{letter} Example: /conditions/atoz/A

/conditions/?category={letter} Example: /conditions/?category=A

Genders

GET /conditions/genders

After looking at the analytics there was a decision to retire the body parts condition filter so this will not be available on the Content API.

Subjects

GET /conditions/subjects

/conditions/?topic={Topic} Note: This will be available in a future release.

Sections since

GET /conditions/sectionssince/{Year}/{Month}/{Day} Example: /conditions/sectionssince/2017/6/12

/conditions/?orderBy=dateModified&startDate={YYYY-MM-DD} Example: /conditions/?orderBy=dateModified&startDate=2017-06-12

Article GET /conditions/articles/{Condition}/{Page} Example: /conditions/articles/acne/introduction

/conditions/{Condition}/{subPage} Example: /conditions/acne

http://www.nhs.uk/news

api.nhs.uk/news

API Migration Guide


Content API Query Parameters

To take advantage of the new features introduced in the Content API you will need to get used to the query parameters available.

Behind the Headlines parameters

Parameter Type Value Description

startDate string YYYY-MM-DD Filters articles after a specific date

endDate string YYYY-MM-DD Filters articles before a specific date

order string newest | oldest Order by newest or oldest published date

page string number Pagination

Conditions parameters

Parameter Type Value Description

startDate string YYYY-MM-DD Filters conditions which are equal or greater than the startDate based on the orderBy parameter.

endDate string YYYY-MM-DD Filters conditions which are equal or less than the endDate based on the orderBy parameter.

order string newest | oldest Order by newest or oldest relating to the orderBy parameter.

page string number Pagination

category string Single letter Filters the conditions by A-Z

topic string Topic Filters conditions by keywords (available in future release)

orderBy string dateModified | lastReviewed | nextReview

The values works alongside the startDate, endDate and orderBy parameters but they are not required. If datePublished is selected without the other parameters then it will show 25 items ordered by the newest date.

API Migration Guide


Content API definitions

The Content API uses the Schema.org vocabulary to make it easier for developers who are used to using the shared collection of schemas. As a result, there will be discrepancies between the definitions on V1 and the Content API. The following tables show a comparison between the definitions in XML and JSON under each endpoint.

Behind the Headlines definitions

All articles

Articles by date

Articles since

Categories

Article

All articles

V1 XML

V1 JSON

Content API XML & JSON

Article title Link->

Text

Text significantLink->name

Article URL Link->

Uri

Uri significantLink-> url

Published Date - - significantLink-> mainEntityOfPage->

datePublished

Modified Date - - significantLink-> mainEntityOfPage->

dateModified

Keywords - - significantLink-> mainEntityOfPage->

keywords

Tracking pixel - - interactionStatistic-> interactionService->

url

Articles by date

V1 XML

V1 JSON



Text


Article URL Link->

Uri



datePublished


dateModified


keywords


url

API Migration Guide


Articles since

V1 XML

V1 JSON


Article title Entry->

Text

- significantLink-> name

Article URL Entry->

Uri

- significantLink-> url

Published Date Entry->

published

- significantLink-> mainEntityOfPage->

datePublished

Modified Date Entry->

updated

- significantLink-> mainEntityOfPage->

dateModified

Summary Entry->

summary

- significantLink-> description


keywords

Tracking pixel tracking - interactionStatistic-> interactionService->

url

Categories

V1 XML

V1 JSON



Text


Article URL Link->

Uri



datePublished


dateModified


keywords


url

Article

V1 XML

V1 JSON


Article title title - headline

Copyright holder

rights

- Copyrightholder-> name

Date modified updated

- dateModified

Author logo logo

- author-> logo

Author name Author-> name

- author-> name

API Migration Guide


Author URL Author-> uri

- author-> url

Author Email Author-> email

- author-> email

Article URL link

- url

Tracking pixel tracking

- interactionStatistic->

interactionService-> url

Headline entry-> title

- headline

Summary entry-> summary

- description

Published date entry-> published

- datePublished

Modified date entry-> updated

- dateModified

Categories entry-> category

- keywords

Content body entry-> content

- mainContentOfPage-> text

Copyright entry-> rights


Links to headlines

entry->

bthns:LinksToHeadlines

- relatedLink-> headline

relatedLink-> url

relatedLink-> publication

Links to science entry->

bthns:LinksToScience

- citation-> headline

citation-> url

citation-> publication

Analysed by entry->

bthns:AnalysedBy

- contributor

Edited by entry-> bthns:EditedBy

- author-> name

Conditions definitions

All conditions

Condition content

All conditions

V1 XML

V1 JSON


Condition name Link->

Text


Condition URL Link->

Uri


Condition description

- - significantLink-> description


datePublished

API Migration Guide



dateModified

Last Reviewed & Next Review Date

- - significantLink-> mainEntityOfPage->

lastReviewed


keywords


url

Condition

V1 XML

V1 JSON


Article name title - name

Copyright holder

rights


Date modified updated

- dateModified

Author logo logo

- author-> logo

Author name Author-> name

- author-> name

Author URL Author-> uri

- author-> url

Author Email Author-> email

- author-> email

Article URL link

- url

Tracking pixel tracking

- interactionStatistic->

interactionService-> url

Summary entry-> summary

- description

Published date entry-> published

- lastReviewed

Last Reviewed & Next Review Date

entry-> review - lastReviewed

Modified date entry-> updated

- dateModified

Categories entry-> category

- keywords

Content body entry-> content

- mainContentOfPage-> text

Copyright entry-> rights


Links to headlines

entry->

bthns:LinksToHeadlines

- relatedLink-> headline

relatedLink-> url

relatedLink-> publication

API Migration Guide


Links to science entry->

bthns:LinksToScience

- citation-> headline

citation-> url

citation-> publication

Analysed by entry->

bthns:AnalysedBy

- contributor

Edited by entry-> bthns:EditedBy

- author-> name

Error codes

The Content API follows the same error codes as V1.

Code Status Description

200 OK The representation, as served, is complete and correct

400 Bad Request The client did not send a correctly structured request (can be used to indicate parameters were supplied in an unsupported combination, but we generally prefer to indicate supported combinations by encoding parameters into URI path segments)

401 Unauthorized The user has not supplied valid credentials (in the case of Outbound Syndication, an API key)

404 Not found There is no resource at this address

405 Method not allowed

An invalid HTTP method has been used (for this project – being outbound – only use of GET is indicated)

406 Unacceptable The user has attempted to request a representation of this resource that is not available for the given URI (for example, trying to request an application/json representation of an Atom-based feed)

410 Gone The resource requested is no longer available and no forwarding address is available (for example a comment that has been reported as inappropriate and subsequently removed)

500 Internal Server Error

There was a genuine unhandled exception on the server. The server should have logged this.

Example responses

Here are some example responses for a successful call.

Behind the Headlines 200 response

All pages and Topic

API Migration Guide


{

"interactionStatistic": [

{

"interactionService": {

"url": "<img style='border: 0; width: 1px; height: 1px;' alt=''

src='http://statse.webtrendslive.com/dcs2221tai1ckz5huxw0mfq86_1m2w/njs.gif?dcsuri

=/news&wt.cg_n=Syndication&wt.cg_s=BehindTheHeadlines&synduserid=xxx&syndreviewdat

e=01-09-2017T11:53'/>",

"@type": "Website",

"name": "Webtrends tracking pixel"

},

"@type": "InteractionCounter"

}

],

"contributor": "Bazian",

"relatedLink": [

{

"url": "https://api.nhs.uk/news/?page=2",

"linkRelationship": "Pagination",

"@type": "LinkRole",

"name": "Next Page",

"description": "Link to Next Page"

},

{




"name": "Last Page",

"description": "Link to Last Page"

},

{




"name": "First Page",

"description": "Link to First Page"

},

{

"url": "http://www.nhs.uk/news/",

"linkRelationship": "Self",


"name": "Self",

"description": "Link to nhs.uk Page"

}

],

"license":

"https://www.nhs.uk/aboutNHSChoices/professionals/syndication/Documents/nhs-

choices-standard-licence-terms.pdf",

"author": {

"url": "https://www.nhs.uk",

"logo": "https://www.nhs.uk/nhscwebservices/documents/logo1.jpg",

"email": "[email protected]",

"@type": "Organization",

"name": "NHS Choices"

},

"url": "http://www.nhs.uk/news/",

"dateModified": "2017-07-31T14:54:57.124Z",

"copyrightholder": {

"name": "Crown Copyright",

"@type": "Organization"

},

"significantLink": [

API Migration Guide


{

"name": "Could discovery of 'fat switch' cure obesity? ",

"url": "https://api.nhs.uk/news/obesity/could-discovery-of-fat-switch-

cure-obesity/",

"linkRelationship": "Result",

"mainEntityOfPage": {

"keywords": [

"Obesity"

],

"dateModified": "2017-08-15T20:10:47.069Z",

"@type": "MedicalWebPage",

"datePublished": "2017-08-02T00:00:00Z"

},


"description": "\"Obesity cure possible after discovery of fat

'switch',\" is the somewhat premature headline in The Daily Telegraph. Researchers

have identified a \"biological switch\" that controls when fat cells convert fat

into energy for the body…"

},

{

"name": "More older adults 'may benefit from taking statins,' study

reports",

"url": "https://api.nhs.uk/news/heart-and-lungs/more-older-adults-may-

benefit-from-taking-statins-study-reports/",



"keywords": [

"Heart and lungs"

],

"dateModified": "2017-08-15T20:10:46.657Z",



},


"description": "\"Nearly all men over 60 and women over 75 eligible

for statins, analysis suggests,\" The Guardian reports. This is the finding of a

study that aimed to see how many people in England…"

}

],

"@context": "http://schema.org",

"@type": "SearchResultsPage"

}

Specific page

{

"dateModified": "2017-08-15T20:10:46.657Z",


{




=/news&wt.cg_n=Syndication&wt.cg_s=BehindTheHeadlines&synduserid=xxx&syndreviewdat

e=01-09-2017T12:05'/>",

"@type": "Website",


},


}

],

API Migration Guide


"description": "\"Nearly all men over 60 and women over 75 eligible for

statins, analysis suggests,\" The Guardian reports. This is the finding of a study

that aimed to see how many people in England…",

"license":



"author": {






},

"headline": "More older adults 'may benefit from taking statins,' study

reports",

"citation": [

{


"headline": "Application of the 2014 NICE cholesterol guidelines

in the English population: a cross-sectional analysis",

"url": "http://bjgp.org/content/early/2017/07/31/bjgp17X692141",

"publication": "British Journal of General Practice. Published

online July 31 2017",

"@type": "WebPage",

"author": {

"@type": "Person",

"name": "Ueda P, Lung TW, Clarke P, Danaei G."

}

},

"@type": "CreativeWork"

}

],

"datePublished": "2017-08-01T00:00:00Z",

"keywords": [

"Heart and lungs"

],




},

"url": "http://www.nhs.uk/news/heart-and-lungs/more-older-adults-may-benefit-

from-taking-statins-study-reports/",

"mainContentOfPage": [

{

"position": 1,

"@type": "WebPageElement",

"name": "markdown",

"text": "\"Nearly all men over 60 and women over 75 eligible for

statins, analysis suggests,\" The Guardian reports. \n\nThis is the finding

of a study that aimed to see how many people in England would qualify for statin

use if the 2014 NICE guidelines for statin therapy in adults were followed.

\n\n<a href=\"/conditions/Cholesterol-lowering-medicines-

statins/Pages/Introduction.aspx\">Statins</a> are drugs designed to lower <a

href=\"/conditions/cholesterol/Pages/Introduction.aspx\">cholesterol</a>, and in

turn reduce the risk of a person developing a..."

}

],

"contributor": "Bazian",


"@type": "WebPage",

"relatedLink": [

{


API Migration Guide


"headline": "Nearly all men over 60 and women over 75 eligible for

statins, analysis suggests",

"url": "https://www.theguardian.com/society/2017/aug/01/nearly-

all-men-over-60-and-women-over-75-eligible-for-statins-analysis-suggests",

"@type": "WebPage",

"publication": "The Guardian"

},

"linkRelationship": "Links to the Headlines",


"description": "Nearly all men over 60 and women over 75 eligible for

statins, analysis suggests"

},

{


"headline": "Statins should be made available for majority of over

60s, study claims",

"url": "http://www.itv.com/news/2017-08-01/statins-should-be-made-

available-for-majority-of-over-60s-study-claims/",

"@type": "WebPage",

"publication": "ITV News"

},

"linkRelationship": "Links to the Headlines",


"description": "Statins should be made available for majority of over

60s, study claims"

}

]

}

Conditions 202 response

All conditions

{


{




=/conditions&wt.cg_n=Syndication&wt.cg_s=Conditions&synduserid=1&syndreviewdate=10

-10-2017T09:43'/>",

"@type": "Website",


},


}

],

"relatedLink": [

{

"url": "https://api.nhs.uk/conditions/?page=2",



"name": "Next Page",

"description": "Link to Next Page"

API Migration Guide


},

{




"name": "Last Page",

"description": "Link to Last Page"

},

{




"name": "First Page",

"description": "Link to First Page"

},

{

"url": "http://www.nhs.uk/conditions/",

"linkRelationship": "Self",


"name": "Self",

"description": "Link to nhs.uk Page"

}

],

"license":



"author": {






},

"url": "http://www.nhs.uk/conditions/",




},

"significantLink": [

{

"name": "Abdominal aortic aneurysm screening",

"url": "https://api.nhs.uk/conditions/abdominal-aortic-aneurysm-screening",



"keywords": [

"Mental health",

"Medical practice"

],

"lastReviewed": [

"2017-10-09T17:00:00Z",

"2019-10-09T17:00:00Z"

],

"dateModified": "2017-10-10T09:30:39.827Z",



},


"description": "Abdominal aortic aneurysm (AAA) screening is a way of

checking if there's a bulge or swelling in the aorta, the main blood vessel that

runs from your heart down through your tummy."

},

{

"name": "Abdominal pain",

API Migration Guide


"url": "https://api.nhs.uk/conditions/stomach-ache-abdominal-pain",



"keywords": [

"Food and diet"

],

"lastReviewed": [

"2017-10-09T17:00:00Z",

"2019-10-09T17:00:00Z"

],

"dateModified": "2017-10-09T12:57:20.938Z",



},


"description": "A stomach ache, including stomach cramps or abdominal pain,

doesn't usually last long and isn't usually caused by anything serious. "

}

],


"@type": "SearchResultsPage"

}

Condition

{

"@context" : "http://schema.org",

"@type" : "MedicalWebPage",

"name" : "Chickenpox ",

"description" : "Chickenpox is a common illness that mainly affects children and

causes an itchy, spotty rash.",

"breadcrumb" : {

"@context" : "http://schema.org",

"@type" : "BreadcrumbList",

"itemListElement" : [

{

"@type" : "ListItem",

"position" : 1,

"item" : {

"@id" : "/conditions",

"name" : "Conditions"

}

},

{

"@type" : "ListItem",

"position" : 2,

"item" : {

"@id" : "/conditions/chickenpox/",

"name" : "Chickenpox"

}

}

]

},

"relatedLink" : [

{

"@type" : "LinkRole",

"url" : "/conditions/chickenpox/",

"linkRelationship" : "Navigation",

"position" : "1",

"name" : "Introduction"

API Migration Guide


},

{


"url" : "/conditions/chickenpox/complications/",


"position" : "2",

"name" : "Complications"

},

{


"url" : "/conditions/chickenpox/pre/",


"position" : "3",

"name" : "Prevention"

},

{


"url" : "/conditions/chickenpox/symptoms/",


"position" : "4",

"name" : "Symptoms"

},

{


"url" : "/conditions/chickenpox/treatment/",


"position" : "5",

"name" : "Treatment"

}

],

"mainEntityOfPage" : [

{

"position" : 1,

"@type" : "WebPageElement",

"name" : "markdown",

"identifier" : "1",

"text" : "<h1>Introduction</h1>Chickenpox is a common illness

that mainly affects children and causes an itchy, spotty

rash.\nMost children will catch chickenpox at some point. It can

also occur in adults who didn't have it when they were a

child.\nIt's usually mild and clears up in a week or so, but it can be

dangerous for some people, such as pregnant women, newborn babies and

people with a weakened immune system.\nThis page

covers:\nSymptoms\nHow to treat it at home\nWhen to get

medical advice\nHow you catch it\nPossible

complications\nFrequently asked questions (FAQs)..."

}

],

"license" :



"author" : {

"url" : "https://www.nhs.uk",

"logo" : "https://www.nhs.uk/nhscwebservices/documents/logo1.jpg",

"email" : "[email protected]",

"@type" : "Organization",

"name" : "NHS Choices"

},

"keywords" : [],

"copyrightholder" : {

"name" : "Crown Copyright",

"@type" : "Organization"

},

API Migration Guide


"url" : "http://www.nhs.uk/conditions/chickenpox",

"dateModified" : "2017-06-26T00:00:00Z",

"lastReviewed" : [

"2018-10-18T00:00:00Z",

"2019-10-18T00:00:00Z"

],

"interactionStatistic" : [

{

"interactionService" : {

"url" : "<img style='border: 0; width: 1px; height: 1px;' alt=''


=&wt.cg_n=&wt.cg_s=&synduserid=&syndreviewdate='/>",

"@type" : "Website",

"name" : "Webtrends tracking pixel"

},

"@type" : "InteractionCounter"

}

]

}

Widgets

The widgets we have on offer are being updated to incorporate the Content API. The new widgets will require an account to the API Developer Portal (developer.api.nhs.uk). To view a list of widgets go to https://developer.api.nhs.uk/widgets.

developer.api.nhs.uk

https://developer.api.nhs.uk/widgets