-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathswagger.yaml
204 lines (204 loc) · 7.37 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
swagger: "2.0"
info:
description: "Used to search for possible options for a dimension within a published dataset.
Only certain dimensions, which can be represented as hierarchies, will be searchable."
version: "1.0.0"
title: "Search within a dataset"
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"
schemes:
- "http"
parameters:
dimension_name:
name: name
description: "A dimension from a dataset."
in: path
required: true
type: string
edition:
name: edition
description: "An edition of a dataset"
in: path
required: true
type: string
id:
name: id
description: "Id that represents a dataset"
in: path
required: true
type: string
instance_id:
name: instance_id
description: "A unique id for an instance."
in: path
required: true
type: string
limit:
name: limit
description: "The number of items requested, defaulted to 50 and limited to 1000."
in: query
type: integer
offset:
name: offset
description: "The first row of resources to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter."
in: query
type: integer
query:
name: q
description: "The query text to search datasets with."
in: query
type: string
required: true
version:
name: version
description: "A version of a dataset"
in: path
required: true
type: string
securityDefinitions:
FlorenceAPIKey:
name: florence-token
description: "API key used to allow florence users to be able to preview the dimension search for an unpublished version."
in: header
type: apiKey
paths:
/dimension-search/datasets/{id}/editions/{edition}/versions/{version}/dimensions/{name}:
get:
tags:
- "Public"
summary: "Search for an option within a hierarchical dimension"
description: "Perform a search on dimension options which are within a hierarchy of a published version of a dataset by the ONS."
parameters:
- $ref: '#/parameters/id'
- $ref: '#/parameters/edition'
- $ref: '#/parameters/version'
- $ref: '#/parameters/dimension_name'
- $ref: '#/parameters/limit'
- $ref: '#/parameters/offset'
- $ref: '#/parameters/query'
produces:
- "application/json"
responses:
200:
description: "A json list containing search results of dimension options which are within a hierarchy of a published version of a dataset by the ONS."
schema:
$ref: '#/definitions/Dimension_Options'
400:
$ref: '#/responses/InvalidRequestError'
404:
$ref: '#/responses/NotFoundError'
500:
$ref: '#/responses/InternalError'
/dimension-search/instances/{instance_id}/dimensions/{name}:
put:
tags:
- "Private user"
summary: "Create a search index"
description: "Create a search index containing a list of dimension options for an instance"
parameters:
- $ref: '#/parameters/instance_id'
- $ref: '#/parameters/dimension_name'
responses:
200:
description: "The index was created"
404:
$ref: '#/responses/NotFoundError'
500:
$ref: '#/responses/InternalError'
delete:
tags:
- "Private user"
summary: "Delete a search index"
description: "Remove a search index containing a list of dimension options for an instance"
parameters:
- $ref: '#/parameters/instance_id'
- $ref: '#/parameters/dimension_name'
responses:
200:
description: "The index was removed"
404:
description: "The index was not found"
500:
$ref: '#/responses/InternalError'
responses:
MethodNotDefinedError:
description: "Method for existing path does not exist."
InvalidRequestError:
description: "Failed to process the request due to invalid request."
InternalError:
description: "Failed to process the request due to an internal error."
NotFoundError:
description: "Dimension or option not found."
definitions:
Dimension_Options:
description: "The resulting resource of the completed search against a dimension hierarchy."
type: object
required: ["count","limit", "items", "offset", "total_count"]
properties:
count:
description: "The number of items returned."
type: integer
items:
description: "The results of the completed search against a dimension hierarchy."
type: array
items:
$ref: '#/definitions/HierarchyDimensionOptionResponse'
limit:
description: "The number of items requested, defaulted to 50 and limited to 1000."
type: integer
offset:
description: "The first row of items to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter. The total number of items that one can page through is limited to 1000 items."
type: integer
HierarchyDimensionOptionResponse:
description: "An individual result of the completed search of dimension hierarchy."
type: object
required: ["code", "dimension_option_url", "has_data", "label", "matches", "number_of_children"]
properties:
code:
type: string
description: "The code for this dimension option."
dimension_option_url:
type: string
description: "The id of a collection of datasets that a dataset is associated to."
has_data:
type: boolean
description: "Indicator to show whether there is an observation value corresponding to the dimension option."
label:
type: string
description: "The label for this dimension option."
matches:
$ref: '#/definitions/Matches'
number_of_children:
type: integer
description: "The number of first generation descendents to this dimension option within the hierarchy."
Matches:
description: "A list of members and arrays of character offset, defining substrings that matched the search terms."
type: object
properties:
code:
description: "An array of character offset into the `code` string. These always occur in pairs, and define the start and end of substrings in the member `code` that matched the search terms. The first character of the string is index 1. "
type: array
items:
$ref: '#/definitions/Snippet'
label:
description: "An array of character offsets into the `label` string. These always occur in pairs, and define the start and end of substrings in the member `label` that matched the search terms. The first character of the string is index 1."
type: array
items:
$ref: '#/definitions/Snippet'
Snippet:
description: "A pair of integers to define the start and end of substring in the member that matched the search terms. The first character of the string is index 1."
type: object
properties:
start:
type: integer
description: "An integer to define the start of a substring in the member that matched. The first character of the string is index 1."
example: 3
end:
type: integer
description: "An integer to define the end of a substring in the member that matched."
example: 8