Skip to content

Commit 918168f

Browse files
adrianparradrianparr
authored
Update spec document (#64)
* Mentioned the ‘Development’ environment, saying it is ‘Not used’ * Added the ‘NHS services’ endpoint * Spec updates
1 parent a7451ee commit 918168f

1 file changed

Lines changed: 88 additions & 30 deletions

File tree

‎specification/nhs-website-content-api.yaml‎

Lines changed: 88 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,22 @@ info:
1111
You can reuse the content from the following sections of the NHS website:
1212
* [Health A to Z (conditions)](https://www.nhs.uk/conditions/)
1313
* [Medicines A to Z](https://www.nhs.uk/medicines/)
14-
* [Pregnancy](https://www.nhs.uk/pregnancy/)
1514
* [Mental health](https://www.nhs.uk/mental-health/)
1615
* [Live Well](https://www.nhs.uk/live-well/)
17-
* [Common health questions](https://www.nhs.uk/common-health-questions/)
18-
* [NHS services](https://www.nhs.uk/nhs-services/).
16+
* [Pregnancy](https://www.nhs.uk/pregnancy/)
17+
* [NHS services](https://www.nhs.uk/nhs-services/)
18+
* [Common health questions](https://www.nhs.uk/common-health-questions/).
1919
2020
You cannot use this API to:
2121
* [find services near you](https://www.nhs.uk/nhs-services/services-near-you/)
2222
* get Ratings and Reviews of NHS services.
2323
24+
Pick a page from one of these sections on the [NHS website](https://www.nhs.uk/).
25+
Make a note of the path in the page URL (the bit that appears after '`https://www.nhs.uk/`').
26+
You can then use this path to make API calls to the 'Integration test' environment and the 'Production' environment like so ...\n\n**Integration test environment**\n\n`https://int.api.service.nhs.uk/nhs-website-content/YOUR_PATH_GOES_HERE`\n\n**Production environment**\n\n`https://api.service.nhs.uk/nhs-website-content/YOUR_PATH_GOES_HERE`
27+
2428
## Who can use this API
25-
Anyone can use this API for any purpose, so long as they include an [attribution](#overview--attribution) as outlined below.
29+
Anyone can use this API for any purpose, so long as they have agreed to the [Online connection agreement](https://digital.nhs.uk/developer/guides-and-documentation/online-connection-agreement) during the [onboarding process](https://digital.nhs.uk/developer/guides-and-documentation/onboarding-process) and they include an [attribution](#overview--attribution) as outlined below.
2630
2731
## Attribution
2832
Any syndicated content must incorporate the following attribution (credit) to the NHS website:
@@ -47,6 +51,11 @@ info:
4751
<p>From <a href="https://www.nhs.uk/" target="_blank">www.nhs.uk<a/></p>
4852
```
4953
54+
## Modularised content
55+
The standard content available through our syndication service is based on the full pages on the NHS website. With our modularised content, you can instead choose to use shorter, more specific sections of content (called “modules”) from our pages. This means you can show your users only the content that’s most relevant to them. You can also use this content more easily in services like apps and voice assistants.
56+
57+
For more details see [Modularised NHS content](https://digital.nhs.uk/developer/api-catalogue/nhs-website-content/modularised-nhs-content#about-our-modularised-content).
58+
5059
## API status
5160
This API has moved from the [NHS website developer portal](https://developer.api.nhs.uk/).
5261
It is currently [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).
@@ -85,6 +94,7 @@ info:
8594
| Environment | Base URL |
8695
| ----------------- | ---------------------------------------------------------------------- |
8796
| Sandbox | `https://sandbox.api.service.nhs.uk/nhs-website-content/` |
97+
| Development | Not used |
8898
| Integration test | `https://int.api.service.nhs.uk/nhs-website-content/` |
8999
| Production | Not available yet |
90100
@@ -108,9 +118,22 @@ info:
108118
For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).
109119
110120
## Onboarding
111-
The onboarding journey for this API is currently in development.
121+
You need to get your software approved by us before it can go live with this API. We call this onboarding.
112122
113-
Additional onboarding information exists on the [developer hub](https://digital.nhs.uk//developer/api-catalogue/nhs-syndicated-content/onboarding-support-information).
123+
The [onboarding process](https://digital.nhs.uk/developer/guides-and-documentation/onboarding-process) for this API is currently in development.
124+
125+
During this process you will be asked agree to the [Online connection agreement](https://digital.nhs.uk/developer/guides-and-documentation/online-connection-agreement).
126+
127+
## Caching
128+
Caching of all responses from the NHS website content API is recommended, and you should do so where possible, unless otherwise notified to you by NHS Digital. The cached data should be refreshed no less than once every 7 days. If instructed to refresh cached NHS website content, you must do so immediately.
129+
130+
## Usage caps
131+
Calls to this API are rate limited as follows:
132+
| Environment | Rate limit |
133+
| ----------------- | ------------------------------- |
134+
| Sandbox | 60 requests per minute |
135+
| Integration test | 10 requests per minute |
136+
| Production | 6000 requests per minute |
114137
115138
contact:
116139
name: "NHS Website Content API v2 Support"
@@ -162,7 +185,7 @@ paths:
162185
163186
| HTTP status | Error code | Description |
164187
| ----------- | -------------------------- | --------------------------------------------- |
165-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
188+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
166189
| 403 | ACCESS_DENIED | User cannot perform this action. |
167190
| 404 | RESOURCE_NOT_FOUND | Page not found. |
168191
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
@@ -203,7 +226,7 @@ paths:
203226
204227
| HTTP status | Error code | Description |
205228
| ----------- | -------------------------- | --------------------------------------------- |
206-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
229+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
207230
| 403 | ACCESS_DENIED | User cannot perform this action. |
208231
| 404 | RESOURCE_NOT_FOUND | Page not found. |
209232
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
@@ -253,7 +276,7 @@ paths:
253276
254277
| HTTP status | Error code | Description |
255278
| ----------- | -------------------------- | --------------------------------------------- |
256-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
279+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
257280
| 403 | ACCESS_DENIED | User cannot perform this action. |
258281
| 404 | RESOURCE_NOT_FOUND | Page not found. |
259282
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
@@ -284,7 +307,7 @@ paths:
284307
285308
| HTTP status | Error code | Description |
286309
| ----------- | -------------------------- | --------------------------------------------- |
287-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
310+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
288311
| 403 | ACCESS_DENIED | User cannot perform this action. |
289312
| 404 | RESOURCE_NOT_FOUND | Page not found. |
290313
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
@@ -319,7 +342,41 @@ paths:
319342
320343
| HTTP status | Error code | Description |
321344
| ----------- | -------------------------- | --------------------------------------------- |
322-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
345+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
346+
| 403 | ACCESS_DENIED | User cannot perform this action. |
347+
| 404 | RESOURCE_NOT_FOUND | Page not found. |
348+
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
349+
/live-well:
350+
parameters:
351+
- $ref: "#/components/parameters/apikey"
352+
get:
353+
summary: Get content from the Live Well hub.
354+
operationId: get-live-well
355+
description: |
356+
## Overview
357+
358+
The [Live Well hub](https://www.nhs.uk/live-well/) contains a number of navigational and content pages.
359+
360+
The content of the page can be taken from the `mainEntityOfPage` part of the response. This includes the navigational links to child pages.
361+
362+
At the top level, modularised content of child pages is highlighted by the `hasPart` field. In child pages, only the individual page is shown.
363+
responses:
364+
"200":
365+
description: |
366+
A valid query for the Live Well pages.
367+
content:
368+
application/json:
369+
schema:
370+
$ref: components/schemas/WebPage.json
371+
example:
372+
$ref: components/examples/LiveWellHubPage.json
373+
"4XX":
374+
description: |
375+
An error occurred as follows:
376+
377+
| HTTP status | Error code | Description |
378+
| ----------- | -------------------------- | --------------------------------------------- |
379+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
323380
| 403 | ACCESS_DENIED | User cannot perform this action. |
324381
| 404 | RESOURCE_NOT_FOUND | Page not found. |
325382
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
@@ -354,76 +411,77 @@ paths:
354411
355412
| HTTP status | Error code | Description |
356413
| ----------- | -------------------------- | --------------------------------------------- |
357-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
414+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
358415
| 403 | ACCESS_DENIED | User cannot perform this action. |
359416
| 404 | RESOURCE_NOT_FOUND | Page not found. |
360417
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
361-
/common-health-questions:
418+
/nhs-services:
362419
parameters:
363420
- $ref: "#/components/parameters/apikey"
364421
get:
365-
summary: Get content from the common health questions hub
366-
operationId: get-common-health-questions
422+
summary: Get content from the NHS services hub
423+
operationId: get-nhs-services
367424
description: |
368425
## Overview
369426
370-
The [common health questions hub](https://www.nhs.uk/common-health-questions/) contains a number of navigational and content pages.
427+
The [NHS services hub](https://www.nhs.uk/nhs-services/) contains a number of navigational and content pages.
371428
372-
The main page contains significant links to topic pages, which then contain significant links to the content pages.
429+
The content of the page can be taken from `mainEntityOfPage`. This includes the navigational patterns to child pages.
373430
374-
Content pages use the 'question' schema.org [question](https://schema.org/Question) property.
431+
At the top level, child modularised content is highlighted by the `hasPart` field. In child pages, only the individual page is highlighted.
375432
376433
responses:
377434
"200":
378435
description: |
379-
A valid query for the common health questions pages.
436+
A valid query for the NHS services hub.
380437
content:
381438
application/json:
382439
schema:
383440
$ref: components/schemas/WebPage.json
384441
example:
385-
$ref: components/examples/CommonHealthQuestionsHubPage.json
442+
$ref: components/examples/NhsServicesHubPage.json
386443
"4XX":
387444
description: |
388445
An error occurred as follows:
389446
390447
| HTTP status | Error code | Description |
391448
| ----------- | -------------------------- | --------------------------------------------- |
392-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
449+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
393450
| 403 | ACCESS_DENIED | User cannot perform this action. |
394451
| 404 | RESOURCE_NOT_FOUND | Page not found. |
395452
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
396-
/live-well:
453+
/common-health-questions:
397454
parameters:
398455
- $ref: "#/components/parameters/apikey"
399456
get:
400-
summary: Get content from the Live Well hub.
401-
operationId: get-live-well
457+
summary: Get content from the common health questions hub
458+
operationId: get-common-health-questions
402459
description: |
403460
## Overview
404461
405-
The [Live Well hub](https://www.nhs.uk/live-well/) contains a number of navigational and content pages.
462+
The [common health questions hub](https://www.nhs.uk/common-health-questions/) contains a number of navigational and content pages.
406463
407-
The content of the page can be taken from the `mainEntityOfPage` part of the response. This includes the navigational links to child pages.
464+
The main page contains significant links to topic pages, which then contain significant links to the content pages.
465+
466+
Content pages use the 'question' schema.org [question](https://schema.org/Question) property.
408467
409-
At the top level, modularised content of child pages is highlighted by the `hasPart` field. In child pages, only the individual page is shown.
410468
responses:
411469
"200":
412470
description: |
413-
A valid query for the Live Well pages.
471+
A valid query for the common health questions pages.
414472
content:
415473
application/json:
416474
schema:
417475
$ref: components/schemas/WebPage.json
418476
example:
419-
$ref: components/examples/LiveWellHubPage.json
477+
$ref: components/examples/CommonHealthQuestionsHubPage.json
420478
"4XX":
421479
description: |
422480
An error occurred as follows:
423481
424482
| HTTP status | Error code | Description |
425483
| ----------- | -------------------------- | --------------------------------------------- |
426-
| 401 | ACCESS_DENIED | ApiKey missing, invalid or expired, or calling application not configured for this operation. |
484+
| 401 | ACCESS_DENIED | Api key missing, invalid or expired, or calling application not configured for this operation. |
427485
| 403 | ACCESS_DENIED | User cannot perform this action. |
428486
| 404 | RESOURCE_NOT_FOUND | Page not found. |
429487
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |

0 commit comments

Comments
 (0)