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

Transcription

1 Migrating from v1.syndication.nhschoices.nhs.uk (v1) to api.nhs.uk (Content API) Published August 2017 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.

2 Contents Introduction 3 Migration checklist for developers 3 Authentication and headers 3 Endpoints: v1 Content API mapping 3 Behind the Headlines endpoints 4 Content API Query Parameters 4 Behind the Headlines parameters 4 Content API definitions 4 Behind the Headlines definitions 5 Error codes 7 Example responses 8 Behind the Headlines 202 response 8 Widgets 11 Copyright 2017 Health and Social Care Information Centre. 2

3 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 Subscribe to the All products (trial subscription) at Familiarise yourself with the new Content API syntax. Look through our API developer portal ( where you can try test-drive Content API calls. Figure out which v1 endpoints your app uses, and look up the equivalent ones in API v2 using the sections below. Update your app's code, replacing v1 calls with the Content API calls. If there's functionality missing in v2, 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. Header Key subscription-key Accept Header Value You can view your subscription keys at: application/json application/xml 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 v2 endpoints are in the right column. Copyright 2017 Health and Social Care Information Centre. 3

4 Behind the Headlines endpoints Method Path (v1.syndication.nhschoices.nhs.uk) All articles GET /bth/articles/all /news Articles by date Articles since GET GET /bth/articles/year/month Example: /bth/articles/2017/january /bth/articlessince/year/month/day Example: bth/articlessince/2017/1/1 Categories GET bth/categories/category Example: bth/categories/diabetes Article GET /bth/articles/year/month/articleurl Example: /bth/articles/2017/august/reports-that-womenhave-more-stamina-look-a-little-weak Content API Path (api.nhs.uk) /news/?startdate=yyyy-mm- DD&endDate=YYYY-MM-DD Example: /news/?startdate= &endDate= /news/?startdate=yyyy-mm- DD Example: /news/?startdate= /news/category Example: /news/diabetes /news/category/articleurl Example: /news/lifestyle-andexercise/reports-women-have-more-staminalook-little-weak 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 you would call api.nhs.uk/news. 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 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 and the Content API. Copyright 2017 Health and Social Care Information Centre. 4

5 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 Article title Article URL XML JSON Content API XML & JSON significantname significant url Published Date - - significant mainentityofpage-> datepublished Modified Date - - significant mainentityofpage-> datemodified Keywords - - significant mainentityofpage-> keywords Tracking pixel - - interactionstatistic-> interactionservice-> url Articles by date Article title Article URL XML JSON Content API XML & JSON significantname significant url Published Date - - significant mainentityofpage-> datepublished Modified Date - - significant mainentityofpage-> datemodified Keywords - - significant mainentityofpage-> keywords Tracking pixel - - interactionstatistic-> interactionservice-> url Articles since Article title XML Entry-> JSON Content API XML & JSON - significant name Article URL Entry-> - significant url Copyright 2017 Health and Social Care Information Centre. 5

6 Published Date Modified Date Summary Entry-> published Entry-> updated Entry-> summary - significant mainentityofpage-> datepublished - significant mainentityofpage-> datemodified - significant description Keywords - - significant mainentityofpage-> keywords Tracking pixel tracking - interactionstatistic-> interactionservice-> url Categories Article title Article URL XML JSON Content API XML & JSON significantname significant url Published Date - - significant mainentityofpage-> datepublished Modified Date - - significant mainentityofpage-> datemodified Keywords - - significant mainentityofpage-> keywords Tracking pixel - - interactionstatistic-> interactionservice-> url Article XML JSON Content API XML & 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 Author URL Author-> uri - author-> url Author Author-> - author-> Article URL link - url Tracking pixel tracking - interactionstatistic-> interactionservice-> url Copyright 2017 Health and Social Care Information Centre. 6

7 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 - Copyrightholder-> name Links to headlines Links to science Analysed by entry-> bthns:linkstoheadlines entry-> bthns:linkstoscience entry-> bthns:analysedby - related headline related url related publication - citation-> headline citation-> url citation-> publication - contributor Edited by entry-> bthns:editedby - author-> name Error codes The Content API follows the same error codes as. 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 Copyright 2017 Health and Social Care Information Centre. 7

8 500 Internal Server Error reported as inappropriate and subsequently removed) 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 202 response All pages and Topic "interactionstatistic": [ "interactionservice": "url": "<img style='border: 0; width: 1px; height: 1px;' alt='' src=' =/news&wt.cg_n=syndication&wt.cg_s=behindtheheadlines&synduserid=xxx&syndreviewdat e= t11:53'/>", "@type": "Website", "name": "Webtrends tracking pixel" "@type": "InteractionCounter" "contributor": "Bazian", "relatedlink": [ "url": " "linkrelationship": "Pagination", "name": "Next Page", "description": "Link to Next Page" "url": " "linkrelationship": "Pagination", "name": "Last Page", "description": "Link to Last Page" "url": " "linkrelationship": "Pagination", "name": "First Page", "description": "Link to First Page" "url": " "linkrelationship": "Self", "name": "Self", "description": "Link to nhs.uk Page" Copyright 2017 Health and Social Care Information Centre. 8

9 "license": " "author": "url": " "logo": " " ": "Organization", "name": "NHS Choices" "url": " "datemodified": " T14:54:57.124Z", "copyrightholder": "name": "Crown Copyright", "Organization" "significantlink": [ "name": "Could discovery of 'fat switch' cure obesity? ", "url": " "linkrelationship": "Result", "mainentityofpage": "keywords": [ "Obesity" "datemodified": " T20:10:47.069Z", "@type": "MedicalWebPage", "datepublished": " T00: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": " "linkrelationship": "Result", "mainentityofpage": "keywords": [ "Heart and lungs" "datemodified": " T20:10:46.657Z", "@type": "MedicalWebPage", "datepublished": " T00:00:00Z" "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": " "@type": "SearchResultsPage" Copyright 2017 Health and Social Care Information Centre. 9

10 Specific page "datemodified": " T20:10:46.657Z", "interactionstatistic": [ "interactionservice": "url": "<img style='border: 0; width: 1px; height: 1px;' alt='' src=' =/news&wt.cg_n=syndication&wt.cg_s=behindtheheadlines&synduserid=xxx&syndreviewdat e= t12:05'/>", "@type": "Website", "name": "Webtrends tracking pixel" "@type": "InteractionCounter" "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": "url": " "logo": " " ": "webservices@nhschoices.nhs.uk", "@type": "Organization", "name": "NHS Choices" "headline": "More older adults 'may benefit from taking statins,' study reports", "citation": [ "mainentityofpage": "headline": "Application of the 2014 NICE cholesterol guidelines in the English population: a cross-sectional analysis", "url": " "publication": "British Journal of General Practice. Published online July ", "@type": "WebPage", "author": "@type": "Person", "name": "Ueda P, Lung TW, Clarke P, Danaei G." "@type": "CreativeWork" "datepublished": " T00:00:00Z", "keywords": [ "Heart and lungs" "copyrightholder": "name": "Crown Copyright", "@type": "Organization" "url": " "maincontentofpage": [ "position": 1, "@type": "WebPageElement", "name": "markdown", "text": "<p>\"nearly all men over 60 and women over 75 eligible for Copyright 2017 Health and Social Care Information Centre. 10

11 statins, analysis suggests,\" The Guardian reports. </p>\n\n<p>this 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. </p>\n\n<p><a href=\"/conditions/cholesterol-lowering-medicinesstatins/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", "@context": " "@type": "WebPage", "relatedlink": [ "mainentityofpage": "headline": "Nearly all men over 60 and women over 75 eligible for statins, analysis suggests", "url": " "@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" "mainentityofpage": "headline": "Statins should be made available for majority of over 60s, study claims", "url": " "@type": "WebPage", "publication": "ITV News" "linkrelationship": "Links to the Headlines", "description": "Statins should be made available for majority of over 60s, study claims" ] 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 Copyright 2017 Health and Social Care Information Centre. 11