-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathswagger.yaml
226 lines (223 loc) · 8.64 KB
/
swagger.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
swagger: "2.0"
info:
description: "Used to find information about data observations published by the ONS.
`Datasets` are published in unique `versions`, which are categorized by `edition`.
Data in each version is broken down by `dimensions`, and a unique combination
of dimension `options` in a version can be used to retrieve `observation` level data."
version: "1.0.0"
title: "Explore our data"
license:
name: "Open Government Licence v3.0"
url: "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
basePath: "/v1"
tags:
- name: "Public"
- name: "Private user"
- name: "Private"
schemes:
- "http"
parameters:
id:
name: id
description: "Id that represents a dataset"
in: path
required: true
type: string
edition:
name: edition
description: "An edition of a dataset"
in: path
required: true
type: string
version:
name: version
description: "A version of a dataset"
in: path
required: true
type: string
dimension_options:
description: "The name of the dimension option and a single value; each option (dimension) and corresponding value (code) must exist against the version - e.g. `age=30` or one of the dimension options can be represented by a wildcard value `*` e.g. `geography=*`"
name: "<dimension_options>"
in: query
required: true
type: string
securityDefinitions:
FlorenceAPIKey:
name: florence-token
description: "API key used to allow florence users to create and query the progress of importing a dataset"
in: header
type: apiKey
InternalAPIKey:
name: internal-token
description: "API key used to allow only internal services to update the state of an import job"
in: header
type: apiKey
DownloadServiceAPIKey:
name: x-download-service-token
description: "API key used to allow the download service to access public and private links to a download"
in: header
type: apiKey
paths:
/datasets/{id}/editions/{edition}/versions/{version}/observations:
get:
tags:
- "Public"
summary: "Get specific observations"
description: "Get observations from a version of the dataset. By providing
a single option for each dimension, a single observation will be returned.
A wildcard (*) can be provided for one dimension, to retrieve a list of
observations."
parameters:
- $ref: '#/parameters/edition'
- $ref: '#/parameters/id'
- $ref: '#/parameters/version'
- $ref: '#/parameters/dimension_options'
responses:
200:
description: "Json object containing all metadata for a version"
schema:
$ref: '#/definitions/ObservationsEndpoint'
400:
description: |
Invalid request, reasons can be one of the following:
* query parameters missing expected dimensions
* query parameters contain incorrect dimensions
* too many query parameters are set to wildcard (*) value; only one query parameter can be equal to *
404:
description: |
Resource not found, reasons can be one of the following:
* dataset id was incorrect
* edition was incorrect
* version was incorrect
* observations not found for selected query paramaters
500:
$ref: '#/responses/InternalError'
responses:
InternalError:
description: "Failed to process the request due to an internal error"
definitions:
ObservationsEndpoint:
description: "An object containing information on a list of observations for a given version of a dataset"
type: object
properties:
dimensions:
description: "A list of dimensions for the given query"
type: object
properties:
<dimension name>:
description: "Each field is a dimension (<dimension name>) and will represent a query parameter in the request unless the query parameter is equal to a wildcard value (*)"
type: object
properties:
option:
description: "A list of links to the corresponding dimension codes for the given `dimension_options`"
type: object
properties:
href:
description: "A link to the corresponding dimension code for the given `dimension_option`"
type: string
example: "http://localhost:8080/codelists/AB12CD34/codes/K02000001"
id:
description: "The id of the corresponding dimension code for the given `dimension_option`"
type: string
limit:
description: "The maximum number of observations requested when filtering on query parameters (limited to 10000). Defaults to 10000 observations."
type: integer
links:
$ref: '#/definitions/ObservationLinks'
observations:
description: "A list of observations found when filtering on query parameters"
type: array
items:
properties:
dimensions:
description: "Contains a list of dimension objects associated with an observation. Each dimension combined with the top level list of dimensions result in this single observation only"
type: object
properties:
<dimension name>:
description: "Each field is a dimension (<dimension name>) and will represent a query parameter in the request as long as the query parameter is equal to a wildcard value (*)"
type: object
properties:
href:
description: "A link to the corresponding dimension code for the given `dimension_option`"
example: "http://localhost:8080/codelists/AB12CD34/codes/K02000001"
type: string
id:
description: "The id of the corresponding dimension code for the given `dimension_option`"
type: "string"
label:
description: "The label corresponding to the dimension code for the given `dimension_option`"
type: string
metadata:
description: "Metadata related to the observation found against version of a dataset"
type: array
items:
type: object
properties:
<key>:
description: "A single metadata key-value pair related to the observation found against version of a dataset, for example 'coefficients of variation' or 'data marking'"
type: string
observation:
description: "The observation value for the selection of query parameters (dimensions) chosen"
type: string
required: [observation]
offset:
description: "The offset into the entire list of observations found"
type: integer
total_observations:
description: "The number of observations found"
type: integer
unit_of_measure:
description: "The unit of measure for the dataset observations"
type: string
usage_notes:
description: "A list of usage notes relating to the dataset"
type: array
items:
$ref: '#/definitions/UsageNotes'
UsageNotes:
description: "A note relating to the dataset. This will appear in downloaded datasets"
type: object
properties:
title:
description: "The title of the note"
type: string
note:
description: "The content of the note"
type: string
# Link objects
ObservationLinks:
description: "A list of links related to this resource"
readOnly: true
type: object
properties:
dataset_metadata:
$ref: '#/definitions/MetadataLink'
self:
$ref: '#/definitions/SelfLink'
version:
$ref: '#/definitions/VersionLink'
MetadataLink:
description: "The version metadata that is associated with this resource"
type: object
properties:
href:
description: "A URL for the version metadata this resource relates to"
type: string
SelfLink:
description: "A link to this resource"
readOnly: true
type: object
properties:
href:
description: "A URL to this resource"
type: string
VersionLink:
description: "The dataset version this resource belongs to"
type: object
properties:
href:
description: "A URL to the version this resource relates to"
type: string
id:
description: "The version number this resource relates to"
type: string