-
Notifications
You must be signed in to change notification settings - Fork 0
/
openapi.yml
509 lines (503 loc) · 16.8 KB
/
openapi.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
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
openapi: '3.0.3'
info:
title: Firefox API Proxy
version: '0.3'
license:
name: ISC
url: https://opensource.org/licenses/ISC
servers:
- url: https://firefox-api-proxy.readitlater.com
description: Production environment
- url: https://firefox-api-proxy.getpocket.dev
description: Development environment
- url: http://localhost:4028
description: Local default port
#common components referenced across multiple paths
components:
# Common schema definitions
schemas:
Error:
type: object
properties:
id:
type: string
description: A unique identifier for this particular instance of the error
status:
type: string
description: HTTP status code string associated with the response
title:
type: string
description: A short human readable summary of the error
detail:
type: string
description: A more detailed explanation of the error intended for human debugging
source:
type: object
description: An object containing references to the source of the error
properties:
parameters:
type: string
description: String indicating which URI query parameter caused the error
graphQLError:
type: string
description: An upstream GraphQLError. These are intended for human consumption. The upstream graph is not expected to provide a stable API for these, and they will change without warning. Do not parse these in Firefox.
ErrorResponse:
type: object
required:
- errors
properties:
errors:
description: An array of error objects
type: array
items:
oneOf:
- $ref: '#/components/schemas/Error'
Save:
type: object
required:
- __typename
- id
- givenUrl
properties:
__typename:
type: string
description: Constant identifier for Saves, allowing them to be differentiated when multiple types are returned together.
enum:
- Save
id:
type: string
description: The Saved Item ID.
resolvedUrl:
type: string
nullable: true
description: Resolved URL for a saved item. This includes following any redirects and any parser normalization.
givenUrl:
type: string
description: The URL the user saved to their list.
title:
type: string
nullable: true
description: The title of the saved item as resolved by the parser.
excerpt:
type: string
nullable: true
description: An excerpt from the saved item as resolved by the parser.
domain:
type: string
nullable: true
description: The Domain of the saved item
wordCount:
type: number
nullable: true
description: Numeric string, word count of the item. May be 0 if parsing fails
timeToRead:
type: number
nullable: true
description: Approximate minutes to read the item, based on word_count
topImageUrl:
type: string
nullable: true
description: Primary image from the saved item as resolved by the parser.
PendingSave:
type: object
required:
- id
- givenUrl
- __typename
properties:
__typename:
type: string
description: Constant identifier for PendingSave, allowing them to be differentiated when multiple types are returned together.
enum:
- PendingSave
id:
type: string
description: The Saved Item ID.
givenUrl:
type: string
description: The URL the user saved to their list.
Recommendation:
type: object
description: These items contain similar content to saves, but have been through a curation process and have more guaranteed data.
required:
- __typename
- tileId
- url
- title
- excerpt
- publisher
- imageUrl
properties:
__typename:
type: string
description: Constant identifier for Recommendation type objects.
enum:
- Recommendation
recommendationId:
type: string
description: String identifier for the Recommendation. This value is expected to be different on each request.
tileId:
type: number
deprecated: true
description: Numerical identifier for the Recommendation. This is specifically a number for Fx client and Mozilla data pipeline compatibility. This property will continue to be present because Firefox clients depend on it, but downstream users should use the recommendation id instead when available.
url:
type: string
description: The URL the Recommendation.
title:
type: string
description: The title of the Recommendation.
excerpt:
type: string
description: An excerpt from the Recommendation.
publisher:
type: string
description: The publisher of the Recommendation.
imageUrl:
type: string
description: The primary image for a Recommendation.
timeToRead:
type: integer
description: Article read time in minutes
LegacyFeedItem:
type: object
required:
- id
- title
- url
- excerpt
- domain
- image_src
- raw_image_src
properties:
id:
type: integer
title:
type: string
url:
type: string
excerpt:
type: string
domain:
type: string
image_src:
type: string
raw_image_src:
type: string
time_to_read:
type: integer
LegacySettings:
type: object
properties:
spocsPerNewTabs:
type: number
domainAffinityParameterSets:
type: object
timeSegments:
type: array
items:
type: object
required:
- id
- startTime
- endTime
- weightPosition
properties:
id:
type: string
startTime:
type: integer
endTime:
type: integer
weightPosition:
type: number
recsExpireTime:
type: integer
version:
type: string
# securitySchemes roughly map to authentication middleware
securitySchemes:
# The following schemes prefixed with "WS" all constitute a `WebSession` auth.
# These are all required together for requests that require this auth type.
WSUserAuth:
type: apiKey
in: cookie
name: a95b4b6
description: A portion of `WebSession` legacy auth. A hash of the user's ID.
WSSessionAuth:
type: apiKey
in: cookie
name: d4a79ec
description: A portion of `WebSession` legacy auth. A hash of the session.
WSLookupAuth:
type: apiKey
in: cookie
name: 159e76e
description: A portion of `WebSession` legacy auth. Session lookup.
WSConsumerKeyAuth:
type: apiKey
in: query
name: consumer_key
description: A portion of `WebSession` legacy auth.
# Originally tried to support this via headers and will continue to support
# this alternative, however I suspect this may be causing issues. _ is not
# valid character in headers. Many services allow this through, and this works
# the overwhelming majority of the time. However, there have been client reports
# of rejecting requests due to missing consumer_key, and I suspect some edge case
# could be removing this.
#
# Avoiding confusion around renaming, and just preferring query params first.
WSConsumerKeyAuthAlias:
type: apiKey
in: header
name: consumer_key
description: A portion of `WebSession` legacy auth. This isn't actually a valid header (_ is not permitted), prefer query param.
paths:
/desktop/v1/recommendations:
get:
summary: Gets a list of Recommendations for a Locale and Region. This operation is performed anonymously and requires no auth.
description: Supports Fx desktop version 114 and up.
operationId: getRecommendations
# Intentionally blank security. No auth required.
security:
- WSConsumerKeyAuth: []
- WSConsumerKeyAuthAlias: []
parameters:
- name: count
in: query
required: false
schema:
type: integer
minimum: 1
# Do not exceed maxPageSize https://github.com/Pocket/list-api/blob/main/src/config/index.ts#L107
maximum: 30
default: 30
description: The number of items to return.
- name: locale
in: query
required: true
description: This locale string is Fx domain language, and built from Fx expectations. Parameter values are not case sensitive.
schema:
type: string
enum: [
# relevant docs: https://docs.google.com/document/d/1omclr-eETJ7zAWTMI7mvvsc3_-ns2Iiho4jPEfrmZfo
# fr, es, it are served through this API in Firefox 114,
# and we plan to migrate all NewTab markets in Firefox 116:
fr,
fr-FR,
es,
es-ES,
it,
it-IT,
en,
en-CA,
en-GB,
en-US,
de,
de-DE,
de-AT,
de-CH,
]
- name: region
in: query
required: false
description: This region string is Fx domain language, and built from Fx expectations. Parameter values are not case sensitive. See [Firefox Home & New Tab Regional Differences](https://mozilla-hub.atlassian.net/wiki/spaces/FPS/pages/80448805/Regional+Differences).
schema:
type: string
- name: enableRankingByRegion
in: query
required: false
description: Returns recommendations specific to the region if set to 1.
schema:
type: integer
enum: [0, 1]
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Recommendation'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: This proxy service encountered an unexpected error.
'502':
description: Services downstream from this proxy encountered an unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'504':
description: Requests to downstream services timed out.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v3/firefox/global-recs:
get:
deprecated: true
summary: Used by older versions of Firefox to get a list of Recommendations for a Locale and Region. This operation is performed anonymously and requires no auth.
description: Supports Fx desktop version 115 and below.
operationId: getGlobalRecs
# Intentionally blank security. No auth required.
security:
- WSConsumerKeyAuth: []
- WSConsumerKeyAuthAlias: []
parameters:
- in: query
name: version
description: API version
required: true
schema:
type: integer
minimum: 3
maximum: 3
default: 3
- in: query
name: locale_lang
description: Firefox locale
required: true
schema:
type: string
default: en-US
- in: query
name: region
description: Firefox region
required: false
schema:
type: string
- in: query
name: count
description: Maximum number of items to return
required: false
schema:
type: integer
minimum: 1
maximum: 50
default: 20
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- status
- spocs
- settings
- recommendations
properties:
status:
type: integer
enum:
- 1
spocs:
type: array
settings:
$ref: '#/components/schemas/LegacySettings'
recommendations:
type: array
items:
$ref: '#/components/schemas/LegacyFeedItem'
'404':
description: Invalid request parameters. Originally this was a 400 but to allow for caching via https://cloud.google.com/cdn/docs/using-negative-caching it is now a 404.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: This proxy service encountered an unexpected error.
'502':
description: Services downstream from this proxy encountered an unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'504':
description: Requests to downstream services timed out.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/desktop/v1/recent-saves:
get:
summary: Gets a list of the most recent saves for a specific user.
description: Supports Fx desktop version 113 and up.
operationId: getRecentSaves
security:
# require all WS (WebSession) security schemes together
- WSUserAuth: []
WSSessionAuth: []
WSLookupAuth: []
WSConsumerKeyAuth: []
- WSUserAuth: []
WSSessionAuth: []
WSLookupAuth: []
WSConsumerKeyAuthAlias: []
parameters:
- name: count
in: query
required: false
schema:
type: integer
minimum: 1
# Do not exceed maxPageSize https://github.com/Pocket/list-api/blob/main/src/config/index.ts#L107
# starting small, always easy to increase max but difficult to shrink
maximum: 20
default: 10
description: The number of items to return.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Save'
- $ref: '#/components/schemas/PendingSave'
'404':
description: Invalid request parameters. Originally this was a 400 but to allow for caching via https://cloud.google.com/cdn/docs/using-negative-caching it is now a 404.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Authorization is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: This proxy service encountered an unexpected error.
'502':
description: Services downstream from this proxy encountered an unexpected error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'504':
description: Requests to downstream services timed out.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'