-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathapi.yml
310 lines (307 loc) · 11.6 KB
/
api.yml
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
swagger: "2.0"
info:
title: Draft Annotations API
description: API for reading and writing draft annotations
version: 0.0.1
license:
name: MIT
contact:
name: Universal Publishing
email: [email protected]
host: api.ft.com
basePath: "/"
schemes:
- http
- https
paths:
/drafts/content/{uuid}/annotations:
get:
summary: Get Annotations Drafts for Content
description: Returns the draft annotations for the content with the given uuid.
tags:
- Public API
produces:
- application/json
parameters:
- name: uuid
in: path
description: The UUID of the content
required: true
type: string
x-example: 8df16ae8-0dfd-4859-a5ff-eeb9644bed35
responses:
200:
description: Returns an array of PAC format annotations for the given content uuid.
examples:
application/json:
annotations:
- id: http://www.ft.com/thing/6b43a14b-a5e0-3b63-a428-aa55def05fcb
apiUrl: http://api.ft.com/things/6b43a14b-a5e0-3b63-a428-aa55def05fcb
prefLabel: FT
type: http://www.ft.com/ontology/Topic
400:
description: Invalid uuid supplied
404:
description: Annotations not found
put:
summary: Write Annotations Drafts for Content
description: Returns the draft annotations for the content with the given uuid.
tags:
- Public API
consumes:
- application/json
produces:
- application/json
parameters:
- name: uuid
in: path
description: The UUID of the content
required: true
type: string
x-example: 8df16ae8-0dfd-4859-a5ff-eeb9644bed35
- name: body
in: body
required: true
description: An object containing an array of PAC format annotations for the given content uuid.
schema:
type: object
properties:
annotations:
type: array
items:
type: object
properties:
id:
type: string
description: The canonical ID of the concept
x-example: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
predicate:
type: string
description: The relationship between the concept and this piece of FT content. The list below is non-exhaustive and subject to change.
enum:
- http://www.ft.com/ontology/annotation/about
- http://www.ft.com/ontology/implicitlyAbout
- http://www.ft.com/ontology/annotation/mentions
- http://www.ft.com/ontology/classification/isClassifiedBy
- http://www.ft.com/ontology/implicitlyClassifiedBy
- http://www.ft.com/ontology/hasBrand
type:
type: string
description: The type of concept, i.e. Person, Organisation, Topic
apiUrl:
type: string
description: The FT API url of the concept
x-example: http://api.ft.com/things/5507ab98-b747-3ebc-b816-11603b9009f4
prefLabel:
type: string
description: The preferred display label for the concept.
required:
- id
- predicate
required:
- annotations
example:
annotations:
- id: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
predicate: http://www.ft.com/ontology/annotation/about
responses:
200:
description: Returns the canonicalized input array of annotations that have been successufully written in PAC.
examples:
application/json:
annotations:
- id: http://api.ft.com/things/5507ab98-b747-3ebc-b816-11603b9009f4
predicate: http://www.ft.com/ontology/annotation/about
400:
description: Invalid uuid or annotations body supplied
500:
description: Internal server error
post:
summary: Add annotation to draft annotations
description: Adds an annotation for specified content ID and returns a cannonicalized array of draft annotations for this content.
tags:
- Public API
consumes:
- application/json
parameters:
- name: uuid
in: path
description: The UUID of the content
required: true
type: string
x-example: 8df16ae8-0dfd-4859-a5ff-eeb9644bed35
- name: body
in: body
description: An annotation for specific content
required: true
schema:
type: object
properties:
id:
type: string
description: The UUID of the concept to be added
x-example: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
predicate:
type: string
description: The relationship between the concept and this piece of FT content
x-example: http://www.ft.com/ontology/annotation/about
example:
id: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
predicate: http://www.ft.com/ontology/annotation/about
required:
- id
- predicate
responses:
200:
description: The annotation was successfully saved to the cannonicalized list of annotations in PAC.
400:
description: Invalid content UUID, concept UUID or predicate supplied.
404:
description: The content with the specified UUID was not found.
500:
description: Internal server error
/drafts/content/{uuid}/annotations/{conceptUUID}:
delete:
summary: Delete all annotations with a given concept from the draft annotations for a specified content
description: Returns the draft annotations for the content after the delete operation.
tags:
- Public API
parameters:
- name: uuid
in: path
description: The UUID of the content
required: true
type: string
x-example: 8df16ae8-0dfd-4859-a5ff-eeb9644bed35
- name: conceptUUID
in: path
description: The UUID of the concept to be deleted
required: true
type: string
x-example: 0667615f-499e-4fa6-8130-f3430450228d
responses:
200:
description: The annotation was successfully deleted from the cannonicalized list of annotations in PAC.
400:
description: Invalid content or concept UUID supplied
404:
description: Content with the specified UUID was not found
500:
description: Internal server error
patch:
summary: Replace all annotations with given conceptUUID from the draft annotations for a specified content with new annotation provided in the body
description: Returns the draft annotations for the content after the replace operation.
tags:
- Public API
consumes:
- application/json
parameters:
- name: uuid
in: path
description: The UUID of the content
required: true
type: string
x-example: 8df16ae8-0dfd-4859-a5ff-eeb9644bed35
- name: conceptUUID
in: path
description: The UUID of the concept to be replaced
required: true
type: string
x-example: ababe00a-d732-4690-b283-585e7f264d2f
- name: body
in: body
description: An annotation for specific content
required: true
schema:
type: object
properties:
id:
type: string
description: The UUID of the new concept
x-example: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
predicate:
type: string
description: The relationship between the concept and this piece of FT content
x-example: http://www.ft.com/ontology/annotation/mentions
example:
id: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
predicate: http://www.ft.com/ontology/annotation/mentions
required:
- id
responses:
200:
description: The annotation was successfully replaced in the cannonicalized list of annotations in PAC.
400:
description: Invalid content or concept UUID supplied
404:
description: Content with the specified UUID was not found
500:
description: Internal server error
/__health:
get:
summary: Healthchecks
description: Runs application healthchecks and returns FT Healthcheck style json.
produces:
- application/json
tags:
- Health
responses:
200:
description: >
Should always return 200 along with the output of the healthchecks - regardless
of whether the healthchecks failed or not.
Please inspect the overall ok property to see whether or not the application is healthy.
examples:
application/json:
schemaVersion: 1
systemCode: draft-annotations-api
name: draft-annotations-api
description: PAC Draft Annotations API
checks:
- id: check-api-health
name: Check API Health
ok: false
severity: 1
businessImpact: A business impact this failure might have
technicalSummary: A technical description of what's gone wrong
panicGuide: https://runbooks.in.ft.com/draft-annotations-api
checkOutput: Technical output from the check
lastUpdated: 2017-08-03T10:44:32.324709638+01:00
ok: true
/__build-info:
get:
summary: Build Information
description: >
Returns application build info, such as the git repository and revision,
the golang version it was built with, and the app release version.
produces:
- application/json; charset=UTF-8
tags:
- Info
responses:
200:
description: Outputs build information as described in the summary.
examples:
application/json; charset=UTF-8:
version: 0.0.1
repository: https://github.com/Financial-Times/app-name.git
revision: 7cdbdb18b4a518eef3ebb1b545fc124612f9d7cd
builder: go version go1.6.3 linux/amd64
dateTime: "20161123122615"
/__gtg:
get:
summary: Good To Go
description: Lightly healthchecks the application, and returns a 200 if it's Good-To-Go.
tags:
- Health
produces:
- text/plain; charset=US-ASCII
responses:
200:
description: The application is healthy enough to perform all its functions correctly - i.e. good to go.
examples:
text/plain; charset=US-ASCII: OK
503:
description: >
One or more of the applications healthchecks have failed,
so please do not use the app. See the /__health endpoint for more detailed information.