This repository has been archived by the owner on Jun 22, 2023. It is now read-only.
forked from alphagov/content-store
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathopenapi.yaml
523 lines (510 loc) · 24.1 KB
/
openapi.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
openapi: '3.0.0'
info:
title: GOV.UK Content API
description: |
GOV.UK Content API provides a simple and consistent way to request
[GOV.UK](https://www.gov.uk) content as structured data in a predictable
format. It is used within the GOV.UK website as the means for applications
to lookup content in order to render it.
This API accepts HTTP requests and responds with
[JSON](https://en.wikipedia.org/wiki/JSON) data containing the same
published content as is presented on GOV.UK.
version: '1.0.0'
servers:
- url: https://www.gov.uk/api/content
paths:
/{path}:
get:
summary: Lookup GOV.UK content by path
description: |
This is the primary interface to lookup the content required to render
a page on GOV.UK
It accepts an input of the path of the page you are looking up. For
example, if you were looking up travel advice for Thailand which is
hosted on GOV.UK at `https://www.gov.uk/foreign-travel-advice/thailand`
you would make a request to
`https://www.gov.uk/api/content/foreign-travel-advice/thailand`.
If the content is available at the requested path you will receive
a [`ContentItem`](#contentitem) containing the structured data for that
page.
tags:
- Content
parameters:
- name: 'path'
in: path
required: true
description: |
The path to the content on GOV.UK e.g for
`https://www.gov.uk/vat-rates` you'd use `vat-rates`
schema:
type: string
example: 'vat-rates'
responses:
200:
description: A content item is available at that path.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentItem'
example:
$ref: '#/components/examples/ContentItemExample'
303:
description: A content item at a different location is responsible for the content at this path. [Learn more](https://content-api.publishing.service.gov.uk/getting-started.html#content-that-spans-multiple-pages).
404:
description: No content item is available at that path.
410:
description: The content item is no longer available at that path.
x-code-samples:
"/vat-rates":
lang: shell
source: curl https://www.gov.uk/api/content/vat-rates
components:
schemas:
ContentItem:
description: |
A resource that represents a piece of content on GOV.UK.
It contains metadata that describe common attributes shared between all content, a details for the particular content and a links field to describe relationships with other content.
type: object
required:
- base_path
- document_type
- email_document_supertype
- first_published_at
- government_document_supertype
- links
- navigation_document_supertype
- phase
- public_updated_at
- publishing_app
- schema_name
- updated_at
- user_journey_document_supertype
properties:
analytics_identifier:
type: integer
description: An identifier which clients of the Publishing API can include with an edition for later use in analytics software.
base_path:
type: string
description: The path of the content on GOV.UK - or the shortest one for content that spans multiple sub paths. [Learn more](https://content-api.publishing.service.gov.uk/getting-started.html#base-path).
content_id:
type: string
format: uuid
description: A UUID which represents the public identifier for a piece of content, combined with locale this makes the unique identifier for an individual piece of content. Can be null for redirects / gone content.
description:
type: string
description: A description of the content which can then be displayed publically.
details:
type: object
description: An object representing data that is structured in a format defined by the schema of the edition. This holds the content for the edition, often in a field called body. Can be null for items without content - for example, a redirect. [Learn more](https://content-api.publishing.service.gov.uk/getting-started.html#details).
document_type:
type: string
description: A particular type of document, used to differentiate between documents that are of different types but share the same schema. [Learn more](https://content-api.publishing.service.gov.uk/getting-started.html#document-type-and-schema-name).
email_document_supertype:
type: string
description: High level group for email subscriptions used to identify publications and announcement.
first_published_at:
type: string
format: date-time
description: Can be set by publishing application, otherwise set automatically in Publishing API on first publish and copied on subsequent ones.
government_document_supertype:
type: string
description: Grouping for email subscriptions.
links:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/LinkedContentItem'
description: An object that has collections of [LinkedContentItems](#linkedcontentitem) objects in arrays, which are grouped by a link type.
locale:
type: string
description: The language the document is written in. A fixed list of locales is allowed.
navigation_document_supertype:
type: string
description: Used to filter pages on the new taxonomy-based navigation pages.
phase:
type: string
enum: [alpha, beta, live]
description: The "phase" of an edition can either be alpha, beta or live.
public_updated_at:
type: string
format: date-time
description: Can be set by publishing application, otherwise set automatically in Publishing API each time an edition is published with a major edition.
publishing_app:
type: string
description: The application which published the edition.
publishing_request_id:
type: string
description: The GOV.UK Request ID which was used when the content item was published.
rendering_app:
type: string
description: The application which will be used to render the content of the edition.
schema_name:
type: string
description: The name of the GOV.UK content schema that the request body will be validated against. [Learn more](https://content-api.publishing.service.gov.uk/getting-started.html#document-type-and-schema-name).
title:
type: string
description: The title of the edition, displayed to the user.
updated_at:
type: string
format: date-time
description: Current date time every time the content item changes, which could be an update to one of the dependent links.
user_journey_document_supertype:
type: string
description: Used to distinguish pages used mainly for navigation (finding) from content pages (thing).
withdrawn_notice:
$ref: '#/components/schemas/WithdrawnNotice'
description: If the edition is withdrawn, this will contain the information about when and why it was withdrawn.
example:
$ref: '#/components/examples/ContentItemExample'
LinkedContentItem:
description: |
A LinkedContentItem is an abridged form of ContentItem which is used to represent links between ContentItems.
It is embedded within the `links` field that is used within ContentItem and LinkedContentItem. [Learn more](https://content-api.publishing.service.gov.uk/getting-started.html#links).
type: object
required:
- analytics_identifier
- api_path
- base_path
- content_id
- description
- document_type
- locale
- links
- public_updated_at
- schema_name
- title
- withdrawn
properties:
analytics_identifier:
type: integer
nullable: true
description: An identifier which clients of the Publishing API can include with an edition for later use in analytics software.
api_path:
type: string
nullable: true
description: The base path of the content item, available from the API.
base_path:
type: string
nullable: true
description: The path of the content on GOV.UK - or the shortest one for content that spans multiple sub paths.
content_id:
type: string
format: uuid
description: A UUID which represents the public identifier for a piece of content, combined with locale this makes the unique identifier for an individual piece of content. Can be null for redirects / gone content.
description:
type: string
nullable: true
description: A description of the content which can then be displayed publically.
details:
type: object
description: An object representing data that is structured in a format defined by the schema of the edition. This holds the content for the edition, often in a field called body. Can be null for items without content - for example, a redirect.
document_type:
type: string
description: A particular type of document, used to differentiate between documents that are of different types but share the same schema.
links:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/LinkedContentItem'
description: An object that has collections of [LinkedContentItems](#linkedcontentitem) objects in arrays, which are grouped by a link type.
locale:
type: string
description: The language the document is written in. A fixed list of locales is allowed.
public_updated_at:
type: string
format: date-time
description: Can be set by publishing application, otherwise set automatically in Publishing API each time an edition is published with a major edition.
schema_name:
type: string
description: The name of the GOV.UK content schema that the request body will be validated against.
title:
type: string
description: The title of the edition, displayed to the user.
withdrawn:
type: boolean
description: Holds whether or not the content has been withdrawn.
example:
api_path: /api/content/browse/tax/vat
base_path: /browse/tax/vat
content_id: 895d337a-fa68-4c83-ab79-1c08016afe87
description: Includes online returns, rates, charging and record keeping
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-06-24T13:56:39Z'
schema_name: mainstream_browse_page
title: VAT
withdrawn: false
links: {}
api_url: https://www.gov.uk/api/content/browse/tax/vat
web_url: https://www.gov.uk/browse/tax/vat
WithdrawnNotice:
description: |
A WithdrawnNotice is an object that can be embedded within a ContentItem and is used to explain the reason a piece of content has been withdrawn. [Learn more](https://content-api.publishing.service.gov.uk/getting-started.html#withdrawn-content).
type: object
required:
- explanation
- withdrawn_at
properties:
explanation:
type: string
description: An explanation as to why the content was withdrawn.
withdrawn_at:
type: string
format: date-time
description: The date when the content was withdrawn.
example:
explanation: ! '<div class="govspeak"><p>This guidance has been withdrawn from use
because the Environment Agency no longer provides best practice guidance. See
guidance on <a href="https://www.gov.uk/guidance/prevent-the-spread-of-harmful-invasive-and-non-native-plants">preventing
harmful weeds and invasive non-native plants spreading weeds</a> for information
on controlling specific plants.</p>
</div>'
withdrawn_at: '2016-07-11T15:08:02Z'
examples:
ContentItemExample:
analytics_identifier:
base_path: /vat-rates
content_id: f838c22a-b2aa-49be-bd95-153f593293a3
document_type: answer
email_document_supertype: other
first_published_at: '2016-02-29T09:24:10.000+00:00'
government_document_supertype: other
locale: en
navigation_document_supertype: guidance
phase: live
public_updated_at: '2014-12-12T14:55:23.000+00:00'
publishing_app: publisher
rendering_app: government-frontend
schema_name: answer
title: VAT rates
updated_at: '2017-08-31T11:35:14.024Z'
user_journey_document_supertype: thing
withdrawn_notice: {}
publishing_request_id: 3592-1504179295.816-10.3.3.1-410
links:
mainstream_browse_pages:
- api_path: /api/content/browse/tax/vat
base_path: /browse/tax/vat
content_id: 895d337a-fa68-4c83-ab79-1c08016afe87
description: Includes online returns, rates, charging and record keeping
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-06-24T13:56:39Z'
schema_name: mainstream_browse_page
title: VAT
withdrawn: false
links: {}
api_url: https://www.gov.uk/api/content/browse/tax/vat
web_url: https://www.gov.uk/browse/tax/vat
ordered_related_items:
- api_path: /api/content/tax-on-shopping
base_path: /tax-on-shopping
content_id: ca839010-1a5e-4049-93b5-577a40286701
description: VAT and other taxes on shopping and services, including tax-free
shopping, energy-saving equipment and mobility aids
document_type: guide
locale: en
public_updated_at: '2014-12-18T14:31:58Z'
schema_name: guide
title: Tax on shopping and services
withdrawn: false
links:
mainstream_browse_pages:
- api_path: /api/content/browse/tax/vat
base_path: /browse/tax/vat
content_id: 895d337a-fa68-4c83-ab79-1c08016afe87
description: Includes online returns, rates, charging and record keeping
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-06-24T13:56:39Z'
schema_name: mainstream_browse_page
title: VAT
withdrawn: false
links:
parent:
- api_path: /api/content/browse/tax
base_path: /browse/tax
content_id: 71255733-af6c-4887-9991-9b288d8d431f
description: Includes VAT, debt and inheritance tax
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-04-08T10:48:40Z'
schema_name: mainstream_browse_page
title: Money and tax
withdrawn: false
links: {}
api_url: https://www.gov.uk/api/content/browse/tax
web_url: https://www.gov.uk/browse/tax
api_url: https://www.gov.uk/api/content/browse/tax/vat
web_url: https://www.gov.uk/browse/tax/vat
api_url: https://www.gov.uk/api/content/tax-on-shopping
web_url: https://www.gov.uk/tax-on-shopping
- api_path: /api/content/vat-businesses
base_path: /vat-businesses
content_id: 727e4b52-b760-4bd6-844d-48d8df888e32
description: VAT for business - VAT rates, exempt and zero-rated items, when to
charge VAT, credit and debit notes, discounts and VAT on offers
document_type: guide
locale: en
public_updated_at: '2014-12-19T15:27:25Z'
schema_name: guide
title: Businesses and charging VAT
withdrawn: false
links:
mainstream_browse_pages:
- api_path: /api/content/browse/business/business-tax
base_path: /browse/business/business-tax
content_id: b7d6588c-a056-47fc-9528-0b9ff42c3866
description: Includes Corporation Tax, Capital Gains Tax, Construction Industry
Scheme (CIS) and VAT
document_type: mainstream_browse_page
locale: en
public_updated_at: '2016-11-18T16:02:29Z'
schema_name: mainstream_browse_page
title: Business tax
withdrawn: false
links:
parent:
- api_path: /api/content/browse/business
base_path: /browse/business
content_id: 2e47e500-8d91-4747-b6d8-cf6524d570f1
description: Information about starting up and running a business in the
UK, including help if you're self employed or a sole trader.
document_type: mainstream_browse_page
locale: en
public_updated_at: '2016-11-18T16:02:29Z'
schema_name: mainstream_browse_page
title: Business and self-employed
withdrawn: false
links: {}
api_url: https://www.gov.uk/api/content/browse/business
web_url: https://www.gov.uk/browse/business
api_url: https://www.gov.uk/api/content/browse/business/business-tax
web_url: https://www.gov.uk/browse/business/business-tax
- api_path: /api/content/browse/tax/vat
base_path: /browse/tax/vat
content_id: 895d337a-fa68-4c83-ab79-1c08016afe87
description: Includes online returns, rates, charging and record keeping
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-06-24T13:56:39Z'
schema_name: mainstream_browse_page
title: VAT
withdrawn: false
links:
parent:
- api_path: /api/content/browse/tax
base_path: /browse/tax
content_id: 71255733-af6c-4887-9991-9b288d8d431f
description: Includes VAT, debt and inheritance tax
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-04-08T10:48:40Z'
schema_name: mainstream_browse_page
title: Money and tax
withdrawn: false
links: {}
api_url: https://www.gov.uk/api/content/browse/tax
web_url: https://www.gov.uk/browse/tax
api_url: https://www.gov.uk/api/content/browse/tax/vat
web_url: https://www.gov.uk/browse/tax/vat
api_url: https://www.gov.uk/api/content/vat-businesses
web_url: https://www.gov.uk/vat-businesses
organisations:
- analytics_identifier: D25
api_path: /api/content/government/organisations/hm-revenue-customs
base_path: /government/organisations/hm-revenue-customs
content_id: 6667cce2-e809-4e21-ae09-cb0bdc1ddda3
document_type: organisation
locale: en
public_updated_at: '2015-05-13T10:09:06Z'
schema_name: placeholder
title: HM Revenue & Customs
withdrawn: false
details:
brand: hm-revenue-customs
logo:
formatted_title: HM Revenue<br/>& Customs
crest: hmrc
links: {}
api_url: https://www.gov.uk/api/content/government/organisations/hm-revenue-customs
web_url: https://www.gov.uk/government/organisations/hm-revenue-customs
parent:
- api_path: /api/content/browse/tax/vat
base_path: /browse/tax/vat
content_id: 895d337a-fa68-4c83-ab79-1c08016afe87
description: Includes online returns, rates, charging and record keeping
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-06-24T13:56:39Z'
schema_name: mainstream_browse_page
title: VAT
withdrawn: false
links:
parent:
- api_path: /api/content/browse/tax
base_path: /browse/tax
content_id: 71255733-af6c-4887-9991-9b288d8d431f
description: Includes VAT, debt and inheritance tax
document_type: mainstream_browse_page
locale: en
public_updated_at: '2015-04-08T10:48:40Z'
schema_name: mainstream_browse_page
title: Money and tax
withdrawn: false
links: {}
api_url: https://www.gov.uk/api/content/browse/tax
web_url: https://www.gov.uk/browse/tax
api_url: https://www.gov.uk/api/content/browse/tax/vat
web_url: https://www.gov.uk/browse/tax/vat
topics:
- api_path: /api/content/topic/business-tax/vat
base_path: /topic/business-tax/vat
content_id: 1ddaaacb-0981-4abc-a532-a5111f2bea6b
description: List of information about VAT.
document_type: topic
locale: en
public_updated_at: '2016-11-30T14:17:03Z'
schema_name: topic
title: VAT
withdrawn: false
links: {}
api_url: https://www.gov.uk/api/content/topic/business-tax/vat
web_url: https://www.gov.uk/topic/business-tax/vat
available_translations:
- title: VAT rates
public_updated_at: '2014-12-12T14:55:23Z'
document_type: answer
schema_name: answer
base_path: /vat-rates
description: Current VAT rates - standard 20% and rates for reduced rate and zero-rated
items
api_path: /api/content/vat-rates
withdrawn: false
content_id: f838c22a-b2aa-49be-bd95-153f593293a3
locale: en
api_url: https://www.gov.uk/api/content/vat-rates
web_url: https://www.gov.uk/vat-rates
links: {}
description: Current VAT rates - standard 20% and rates for reduced rate and zero-rated
items
details:
body: ! "\n<div class=\"highlight-answer\">\n<p>The standard <abbr title=\"Value
Added Tax\">VAT</abbr> rate is <em>20%</em></p>\n</div>\n\n<h2 id=\"vat-rates-for-goods-and-services\">\n<abbr
title=\"Value Added Tax\">VAT</abbr> rates for goods and services</h2>\n\n<table>\n
\ <thead>\n <tr>\n <th>Rate</th>\n <th>% of <abbr title=\"Value Added
Tax\">VAT</abbr>\n</th>\n <th>What the rate applies to</th>\n </tr>\n
\ </thead>\n <tbody>\n <tr>\n <td>Standard</td>\n <td>20%</td>\n
\ <td>Most goods and services</td>\n </tr>\n <tr>\n <td>Reduced
rate</td>\n <td>5%</td>\n <td>Some goods and services, eg children’s
car seats and home energy</td>\n </tr>\n <tr>\n <td>Zero rate</td>\n
\ <td>0%</td>\n <td>Zero-rated goods and services, eg most food and children’s
clothes</td>\n </tr>\n </tbody>\n</table>\n\n<p>The standard rate of <abbr
title=\"Value Added Tax\">VAT</abbr> increased to 20% on 4 January 2011 (from
17.5%).</p>\n\n<p>Some things are exempt from <abbr title=\"Value Added Tax\">VAT</abbr>,
eg postage stamps, financial and property transactions.</p>\n\n<p>The <a href=\"/vat-businesses/vat-rates\"><abbr
title=\"Value Added Tax\">VAT</abbr> rate businesses charge</a> depends on their
goods and services.</p>\n\n<p>Check the <a href=\"https://www.gov.uk/rates-of-vat-on-different-goods-and-services\">rates
of <abbr title=\"Value Added Tax\">VAT</abbr></a> on different goods and services.</p>\n\n"