Skip to content

Commit 07b66bb

Browse files
adrianparradrianparr
committed
Trying again!
1 parent b3974ef commit 07b66bb

1 file changed

Lines changed: 52 additions & 102 deletions

File tree

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

Lines changed: 52 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,35 @@
11
# This is an OpenAPI Specification (https://swagger.io/specification/)
2-
# for nhs-website-content-api owned by NHS Digital (https://digital.nhs.uk/)
2+
# for the nhs-website-content-api owned by NHS England (https://digital.nhs.uk/)
33
openapi: "3.0.0"
44
info:
55
title: "nhs-website-content-api"
66
version: "Computed and injected at build time by `scripts/set_version.py`"
77
description: |
88
## Overview
9-
Use this API to get page content from the [NHS website](https://www.nhs.uk)
10-
11-
You can reuse the following content from the NHS website:
12-
* health conditions
13-
* medicines
14-
* pregnancy
15-
* mental health
16-
* live well
17-
* common health questions
18-
* information about NHS services
19-
20-
You cannot currently use this API to:
9+
This API provides content from the [NHS website](https://www.nhs.uk) as JSON, to be consumed programmatically and used by your application.
10+
11+
You can reuse the content from the following sections of the NHS website:
12+
* [Health A to Z (conditions)](https://www.nhs.uk/conditions/)
13+
* [Medicines A to Z](https://www.nhs.uk/medicines/)
14+
* [Pregnancy](https://www.nhs.uk/pregnancy/)
15+
* [Mental health](https://www.nhs.uk/mental-health/)
16+
* [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/).
19+
20+
You cannot use this API to:
2121
* [find services near you](https://www.nhs.uk/nhs-services/services-near-you/)
22+
* get Ratings and Reviews of NHS services.
2223
2324
## Who can use this API
24-
Anyone can use this API. Users need to agree to our [terms and conditions](https://developer.api.nhs.uk/about/terms)
25+
Anyone can use this API for any purpose, so long as they include an attribution as per our [terms and conditions](https://developer.api.nhs.uk/about/terms).
2526
26-
## API status and roadmap
27-
This API has moved from the [NHS website developer portal](https://developer.api.nhs.uk/). It is currently [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).
27+
## API status
28+
This API has moved from the [NHS website developer portal](https://developer.api.nhs.uk/).
29+
It is currently [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).
2830
2931
## Service level
30-
31-
This API is a [gold service](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels), meaning that it is operational and supported 24 x 7 x 365
32+
This API is a [gold service](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels), meaning that it is operational and supported 24 hours a day, 365 days a year.
3233
3334
## Technology
3435
This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).
@@ -47,35 +48,26 @@ info:
4748
This access mode is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user.
4849
4950
To use this access mode, use the following security pattern:
50-
* [Application-restricted RESTful API - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication)
51+
* [Application-restricted RESTful API - API key authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication).
52+
53+
## Errors
54+
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
55+
* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
56+
* 400 to 499 if it failed because of a client error by your application
57+
* 500 to 599 if it failed because of an error on our server.
58+
59+
Errors specific to each endpoint are shown in the endpoints section, under response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.
5160
5261
## Environments and testing
5362
| Environment | Base URL |
5463
| ----------------- | ---------------------------------------------------------------------- |
5564
| Integration test | `https://int.api.service.nhs.uk/nhs-website-content/` |
5665
| Production | Not available yet |
5766
58-
## Integration testing
59-
Our integration test environment:
60-
61-
* is for formal integration testing.
62-
* includes application authentication
63-
* contains a replica of our live data, but has a [reduced call rate](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits)
64-
6567
## Onboarding
6668
The onboarding journey for this API is currently in development.
6769
68-
Additional onboarding information exists on the [developer hub](https://digital.nhs.uk//developer/api-catalogue/nhs-syndicated-content/onboarding-support-information)
69-
70-
## Errors
71-
We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:
72-
73-
200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
74-
400 to 499 if it failed because of a client error by your application
75-
500 to 599 if it failed because of an error on our server
76-
For details of 2xx and 4xx responses for a specific API, see its API specification.
77-
78-
Errors specific to each endpoint are shown in the endpoints section, under response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.
70+
Additional onboarding information exists on the [developer hub](https://digital.nhs.uk//developer/api-catalogue/nhs-syndicated-content/onboarding-support-information).
7971
8072
contact:
8173
name: "nhs-website-content-api API Support"
@@ -89,7 +81,7 @@ servers:
8981
paths:
9082
/conditions:
9183
parameters:
92-
- $ref: "#/components/parameters/apiKey"
84+
- $ref: "#/components/parameters/apikey"
9385
- $ref: "#/components/parameters/order"
9486
- $ref: "#/components/parameters/page"
9587
- $ref: "#/components/parameters/category"
@@ -109,22 +101,10 @@ paths:
109101
110102
There are a number of query parameters that filter the output.
111103
112-
| Query parameter | Description | Type |
113-
| ----------------- | ---------------------------------------------------------------------- | ----------- |
114-
| order | Order by 'newest' or 'oldest' | string |
115-
| page | Page number, used to filter paginated results | int |
116-
| category | Filters child pages by letters A-Z. | string |
117-
| synonyms | Include multiple listings for pages with more than one name | boolean |
118-
| childArticles | Include child pages of a topic within results under property subjectOf | boolean |
119-
| status | Filter by "published" or "unpublished" | string |
120-
121104
responses:
122105
"200":
123106
description: |
124107
A valid query for the conditions.
125-
headers:
126-
apikey:
127-
$ref: "#/components/headers/apiKey"
128108
content:
129109
application/schema+json:
130110
schema:
@@ -143,7 +123,7 @@ paths:
143123
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
144124
/conditions/*:
145125
parameters:
146-
- $ref: "#/components/parameters/apiKey"
126+
- $ref: "#/components/parameters/apikey"
147127
- $ref: "#/components/parameters/modules"
148128
get:
149129
summary: Get details of a condition page
@@ -166,9 +146,6 @@ paths:
166146
"200":
167147
description: |
168148
A valid query which returns a page object for the chosen page
169-
headers:
170-
apiKey:
171-
$ref: "#/components/headers/apiKey"
172149
content:
173150
application/schema+json:
174151
schema:
@@ -187,7 +164,7 @@ paths:
187164
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
188165
/medicines:
189166
parameters:
190-
- $ref: "#/components/parameters/apiKey"
167+
- $ref: "#/components/parameters/apikey"
191168
- $ref: "#/components/parameters/startDate"
192169
- $ref: "#/components/parameters/endDate"
193170
- $ref: "#/components/parameters/order"
@@ -207,30 +184,18 @@ paths:
207184
208185
There are a number of query parameters that filter the output.
209186
210-
| Query parameter | Description | Type |
211-
| ----------------- | ---------------------------------------------------------------------- | ----------- |
212-
| startDate | Gets medicines which are equal or greater than the startDate (see below) | string |
213-
| endDate | Gets medicines which are equal or greater than the endDate (see below) | string |
214-
| order | Order by 'newest' or 'oldest' | string |
215-
| page | Page number, used to filter paginated results | int |
216-
| category | Filters child pages by letters A-Z. | string |
217-
| orderBy | works alongside startDate and endDate (details below) | string |
218-
219187
## Ordering by dates
220188
221189
The `orderBy` parameter can be `dateModified`, `lastReviewed` and `nextReview`. By default if any of the `orderBy` parameters are chosen the results are sorted by newest first.
222190
223191
However, the `orderBy` parameter can be used with the `startDate` and `endDate` parameters to filter down to the desired date. `startDate` and `endDate` should be given in the YYYY-MM-DD format.
224192
225-
For example `https://api.nhs.uk/medicines?apiKey=xxx&startDate=2022-01-01&orderBy=dateModified`
193+
For example `https://api.nhs.uk/medicines?apikey=xxx&startDate=2022-01-01&orderBy=dateModified`
226194
227195
responses:
228196
"200":
229197
description: |
230198
A valid query for medicines.
231-
headers:
232-
apiKey:
233-
$ref: "#/components/headers/apiKey"
234199
content:
235200
application/schema+json:
236201
schema:
@@ -249,22 +214,19 @@ paths:
249214
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
250215
/medicines/*:
251216
parameters:
252-
- $ref: "#/components/parameters/apiKey"
217+
- $ref: "#/components/parameters/apikey"
253218
get:
254-
summary: Get specific medicines pages
219+
summary: Get specific medicine page
255220
operationId: get-medicine-page
256221
description: |
257222
## Overview
258-
There is an endpoint for each page under the Medicines A to Z, for example https://www.nhs.uk/medicines/amoxicillin
223+
There is an endpoint for each page under the Medicines A to Z, for example https://www.nhs.uk/medicines/amoxicillin.
259224
260225
This can be used to get specific information about individual medicines.
261226
responses:
262227
"200":
263228
description: |
264229
A valid query for medicines.
265-
headers:
266-
apiKey:
267-
$ref: "#/components/headers/apiKey"
268230
content:
269231
application/schema+json:
270232
schema:
@@ -283,7 +245,7 @@ paths:
283245
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
284246
/mental-health:
285247
parameters:
286-
- $ref: "#/components/parameters/apiKey"
248+
- $ref: "#/components/parameters/apikey"
287249
get:
288250
summary: Get content from the mental health hub
289251
operationId: get-mental-health
@@ -300,9 +262,6 @@ paths:
300262
"200":
301263
description: |
302264
A valid query for the mental health hub.
303-
headers:
304-
apiKey:
305-
$ref: "#/components/headers/apiKey"
306265
content:
307266
application/schema+json:
308267
schema:
@@ -321,14 +280,14 @@ paths:
321280
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
322281
/pregnancy:
323282
parameters:
324-
- $ref: "#/components/parameters/apiKey"
283+
- $ref: "#/components/parameters/apikey"
325284
get:
326285
summary: Get content from the pregnancy hub
327286
operationId: get-pregnancy
328287
description: |
329288
## Overview
330289
331-
The pregnancy hub contains a number of navigational and content pages.
290+
The [pregnancy hub](https://www.nhs.uk/pregnancy/) contains a number of navigational and content pages.
332291
333292
The content of the page can be taken from `mainEntityOfPage`. This includes the navigational patterns to child pages.
334293
@@ -338,9 +297,6 @@ paths:
338297
"200":
339298
description: |
340299
A valid query for the pregnancy hub.
341-
headers:
342-
apiKey:
343-
$ref: "#/components/headers/apiKey"
344300
content:
345301
application/schema+json:
346302
schema:
@@ -359,14 +315,14 @@ paths:
359315
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
360316
/common-health-questions:
361317
parameters:
362-
- $ref: "#/components/parameters/apiKey"
318+
- $ref: "#/components/parameters/apikey"
363319
get:
364320
summary: Get content from the common health questions hub
365321
operationId: get-common-health-questions
366322
description: |
367323
## Overview
368324
369-
The [Common health questions hub](https://www.nhs.uk/common-health-questions/) contains a number of navigational and content pages.
325+
The [common health questions hub](https://www.nhs.uk/common-health-questions/) contains a number of navigational and content pages.
370326
371327
The main page contains significant links to topic pages, which then contain significant links to the content pages.
372328
@@ -376,9 +332,6 @@ paths:
376332
"200":
377333
description: |
378334
A valid query for the common health questions pages.
379-
headers:
380-
apiKey:
381-
$ref: "#/components/headers/apiKey"
382335
content:
383336
application/schema+json:
384337
schema:
@@ -397,7 +350,7 @@ paths:
397350
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
398351
/live-well:
399352
parameters:
400-
- $ref: "#/components/parameters/apiKey"
353+
- $ref: "#/components/parameters/apikey"
401354
get:
402355
summary: Get content from the Live Well hub.
403356
operationId: get-live-well
@@ -413,9 +366,6 @@ paths:
413366
"200":
414367
description: |
415368
A valid query for the Live Well pages.
416-
headers:
417-
apiKey:
418-
$ref: "#/components/headers/apiKey"
419369
content:
420370
application/schema+json:
421371
schema:
@@ -434,27 +384,27 @@ paths:
434384
| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |
435385
components:
436386
headers:
437-
apiKey:
387+
apikey:
438388
$ref: components/schemas/ApiKey.yaml
439389
parameters:
440-
apiKey:
441-
name: api_key
390+
apikey:
391+
name: apikey
442392
in: query
443393
description: The API key required to send a successful request.
444394
required: true
445395
schema:
446396
type: string
447397
example: "11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"
448398
startDate:
449-
name: start_date
399+
name: startDate
450400
in: query
451401
description: Earliest date filter, works with orderBy.
452402
required: false
453403
schema:
454404
type: string
455405
example: "2020-01-01"
456406
endDate:
457-
name: end_date
407+
name: endDate
458408
in: query
459409
description: Latest date filter, works with orderBy.
460410
required: false
@@ -464,7 +414,7 @@ components:
464414
order:
465415
name: order
466416
in: query
467-
description: Order by newest or oldest.
417+
description: Order by "newest" or "oldest".
468418
required: false
469419
schema:
470420
type: string
@@ -480,15 +430,15 @@ components:
480430
category:
481431
name: category
482432
in: query
483-
description: Filters child pages by letters A-Z.
433+
description: Filters child pages by letters "A" to "Z".
484434
required: false
485435
schema:
486436
type: string
487437
example: "A"
488438
orderBy:
489-
name: order_by
439+
name: orderBy
490440
in: query
491-
description: works alongside startDate and endDate. Options are `dateModified`, `lastReviewed` and `nextReview`.
441+
description: works alongside startDate and endDate. Options are "dateModified", "lastReviewed" and "nextReview".
492442
required: false
493443
schema:
494444
type: string
@@ -502,7 +452,7 @@ components:
502452
type: boolean
503453
example: true
504454
childArticles:
505-
name: child_articles
455+
name: childArticles
506456
in: query
507457
description: Include child pages of a topic within results under property subjectOf.
508458
required: false

0 commit comments

Comments
 (0)