Skip to content
This repository was archived by the owner on Mar 21, 2024. It is now read-only.

Commit bba69d4

Browse files
gmourierbidoubiwa
gmourier
and
bidoubiwa
committed
API Guideline - Return list of API resources under a results array (#138)
* Place list of documents under a results array on /documents * Add results array for indexes object list * Add the future of indexes pagination * Update open-api.yml * Fix typo * Apply suggestions from code review Co-authored-by: cvermand <[email protected]> * Add offset/limit pagination for indexes and API keys * Try to add multipe refs to a response object Co-authored-by: cvermand <[email protected]>
1 parent 65e7ace commit bba69d4

File tree

4 files changed

+286
-54
lines changed

4 files changed

+286
-54
lines changed

‎open-api.yaml

Lines changed: 97 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,14 @@ components:
2929
type: integer
3030
description: Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value.
3131
example: 10
32+
offset:
33+
type: integer
34+
description: Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value.
35+
example: 0
36+
total:
37+
type: integer
38+
description: Total number of browsable results using offset/limit parameters for the given resource.
39+
example: 50
3240
from:
3341
type: integer
3442
description: The first task uid returned.
@@ -84,7 +92,7 @@ components:
8492
title: American Ninja 5
8593
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
8694
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
87-
release_date: '1993-01-01'
95+
release_date: 725846400
8896
description: 'A document made of attribute. The maximum number of attribute for a document is 65,535.'
8997
matchesPosition:
9098
type: object
@@ -106,13 +114,13 @@ components:
106114
title: American Ninja 5
107115
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
108116
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
109-
release_date: '1993-01-01'
117+
release_date: 725846400
110118
_formatted:
111119
id: 25684
112120
title: American Ninja 5
113121
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
114122
overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
115-
release_date: '1993-01-01'
123+
release_date: 725846400
116124
_matchesPosition:
117125
overview:
118126
- start: 49
@@ -124,13 +132,13 @@ components:
124132
title: American Ninja 5
125133
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
126134
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
127-
release_date: '1993-01-01'
135+
release_date: 725846400
128136
_formatted:
129137
id: 25684
130138
title: American Ninja 5
131139
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
132140
overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
133-
release_date: '1993-01-01'
141+
release_date: 725846400
134142
_matchesPosition:
135143
overview:
136144
- start: 49
@@ -675,14 +683,14 @@ components:
675683
limit:
676684
name: limit
677685
in: query
678-
description: Maximum number of documents to return.
686+
description: Maximum number of results to return.
679687
schema:
680688
type: number
681689
default: 20
682690
offset:
683691
name: offset
684692
in: query
685-
description: Number of documents to skip.
693+
description: Number of results to skip.
686694
schema:
687695
type: number
688696
default: 0
@@ -1014,19 +1022,40 @@ paths:
10141022
content:
10151023
application/json:
10161024
schema:
1017-
type: array
1018-
items:
1019-
$ref: '#/components/schemas/index'
1025+
type: object
1026+
properties:
1027+
results:
1028+
type: array
1029+
items:
1030+
$ref: '#/components/schemas/index'
1031+
limit:
1032+
$ref: '#/components/schemas/limit'
1033+
offset:
1034+
$ref: '#/components/schemas/offset'
1035+
total:
1036+
$ref: '#/components/schemas/total'
1037+
required:
1038+
- results
1039+
- limit
1040+
- offset
1041+
- total
10201042
examples:
10211043
Example:
10221044
value:
1023-
- uid: movies
1024-
name: movies
1025-
primaryKey: movie_id
1026-
createdAt: '2019-11-20T09:40:33.711324Z'
1027-
updatedAt: '2019-11-20T09:40:33.711324Z'
1045+
results:
1046+
- uid: movies
1047+
name: movies
1048+
primaryKey: movie_id
1049+
createdAt: '2019-11-20T09:40:33.711324Z'
1050+
updatedAt: '2019-11-20T09:40:33.711324Z'
1051+
limit: 1
1052+
offset: 0
1053+
total: 1
10281054
'401':
10291055
$ref: '#/components/responses/401'
1056+
parameters:
1057+
- $ref: '#/components/parameters/limit'
1058+
- $ref: '#/components/parameters/offset'
10301059
post:
10311060
operationId: indexes.create
10321061
summary: Create Index
@@ -1192,17 +1221,40 @@ paths:
11921221
content:
11931222
application/json:
11941223
schema:
1195-
type: array
1196-
items:
1197-
$ref: '#/components/schemas/document'
1224+
type: object
1225+
properties:
1226+
results:
1227+
type: array
1228+
items:
1229+
$ref: '#/components/schemas/document'
1230+
limit:
1231+
$ref: '#/components/schemas/limit'
1232+
offset:
1233+
$ref: '#/components/schemas/offset'
1234+
total:
1235+
$ref: '#/components/schemas/total'
1236+
required:
1237+
- results
1238+
- limit
1239+
- offset
1240+
- total
11981241
examples:
11991242
Example:
12001243
value:
1201-
- id: 25684
1202-
title: American Ninja 5
1203-
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
1204-
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
1205-
release_date: '1993-01-01'
1244+
results:
1245+
- id: 25684
1246+
title: American Ninja 5
1247+
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
1248+
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
1249+
release_date: 725846400
1250+
- id: 45881
1251+
title: The Bridge of San Luis Rey
1252+
poster: 'https://image.tmdb.org/t/p/w500/4X7quIcdkc24Cveg5XdpfRqxtYA.jpg'
1253+
overview: "The Bridge of San Luis Rey is American author Thornton Wilder's second novel, first published in 1927 to worldwide acclaim. It tells the story of several interrelated people who die in the collapse of an Inca rope-fiber suspension bridge in Peru, and the events that lead up to their being on the bridge.[ A friar who has witnessed the tragic accident then goes about inquiring into the lives of the victims, seeking some sort of cosmic answer to the question of why each had to die. The novel won the Pulitzer Prize in 1928."
1254+
release_date: 1072915200
1255+
limit: 20
1256+
offset: 0
1257+
total: 2
12061258
'401':
12071259
$ref: '#/components/responses/401'
12081260
'404':
@@ -1290,7 +1342,7 @@ paths:
12901342
title: American Ninja 5
12911343
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
12921344
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
1293-
release_date: '1993-01-01'
1345+
release_date: 725846400
12941346
description: ''
12951347
responses:
12961348
'202':
@@ -1446,13 +1498,13 @@ paths:
14461498
title: American Ninja 5
14471499
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
14481500
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
1449-
release_date: '1993-01-01'
1501+
release_date: 725846400
14501502
_formatted:
14511503
id: 25684
14521504
title: American Ninja 5
14531505
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
14541506
overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
1455-
release_date: '1993-01-01'
1507+
release_date: 725846400
14561508
_matchesPosition:
14571509
overview:
14581510
- start: 49
@@ -1588,13 +1640,13 @@ paths:
15881640
title: American Ninja 5
15891641
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
15901642
overview: 'When a scientists daughter is kidnapped, American Ninja, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the ninja.'
1591-
release_date: '1993-01-01'
1643+
release_date: 725846400
15921644
_formatted:
15931645
id: 25684
15941646
title: American Ninja 5
15951647
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
15961648
overview: 'When a scientists daughter is kidnapped, American <em>Ninja</em>, attempts to find her, but this time he teams up with a youngster he has trained in the ways of the <em>ninja</em>.'
1597-
release_date: '1993-01-01'
1649+
release_date: 725846400
15981650
_matchesPosition:
15991651
overview:
16001652
- start: 49
@@ -2502,6 +2554,17 @@ paths:
25022554
type: array
25032555
items:
25042556
$ref: '#/components/schemas/key'
2557+
limit:
2558+
$ref: '#/components/schemas/limit'
2559+
offset:
2560+
$ref: '#/components/schemas/offset'
2561+
total:
2562+
$ref: '#/components/schemas/total'
2563+
required:
2564+
- results
2565+
- limit
2566+
- offset
2567+
- total
25052568
examples:
25062569
example-1:
25072570
value:
@@ -2515,8 +2578,14 @@ paths:
25152578
expiresAt: '2022-11-12T10:00:00Z'
25162579
createdAt: '2021-11-12T10:00:00Z'
25172580
updatedAt: '2021-11-12T10:00:00Z'
2581+
limit: 20
2582+
offset: 0
2583+
total: 1
25182584
'401':
25192585
$ref: '#/components/responses/401'
2586+
parameters:
2587+
- $ref: '#/components/parameters/limit'
2588+
- $ref: '#/components/parameters/offset'
25202589
'/keys/{key}':
25212590
get:
25222591
summary: Get an API key

‎text/0085-api-keys.md

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -367,8 +367,67 @@ Only the master key allows managing the API keys.
367367
```
368368
"Authorization: Bearer :masterKey"
369369
```
370+
##### Query Parameters
370371

371-
##### Response
372+
| Field | Type | Required |
373+
|--------------------------|--------------------------|----------|
374+
| `offset` | Integer / `null` | false |
375+
| `limit` | Integer / `null` | false |
376+
377+
###### `offset`
378+
379+
- Type: Integer
380+
- Required: False
381+
- Default: `0`
382+
383+
Sets the starting point in the results, effectively skipping over a given number of API keys.
384+
385+
###### `limit`
386+
387+
- Type: Integer
388+
- Required: False
389+
- Default: `20`
390+
391+
Sets the maximum number of documents to be returned by the current request.
392+
393+
##### Response Definition
394+
395+
| Field | Type | Required |
396+
|--------------------------|--------------------------|----------|
397+
| `result` | Array[Key] | true |
398+
| `offset` | Integer | true |
399+
| `limit` | Integer | true |
400+
| `total` | Integer | true |
401+
402+
###### `results`
403+
404+
- Type: Array[Key]
405+
- Required: True
406+
407+
An array containing the fetched API keys.
408+
409+
###### `offset`
410+
411+
- Type: Integer
412+
- Required: True
413+
414+
Gives the `offset` parameter used for the query.
415+
416+
###### `limit`
417+
418+
- Type: Integer
419+
- Required: True
420+
421+
Gives the `limit` parameter used for the query.
422+
423+
###### `total`
424+
425+
- Type: Integer
426+
- Required: True
427+
428+
Gives the total number of API keys that can be browsed.
429+
430+
###### Example
372431

373432
`200 Success`
374433

@@ -416,7 +475,10 @@ Only the master key allows managing the API keys.
416475
"createdAt": "2021-08-11T10:00:00Z",
417476
"updatedAt": "2021-08-11T10:00:00Z"
418477
}
419-
]
478+
],
479+
"offset": 0,
480+
"limit": 20,
481+
"total": 3
420482
}
421483
```
422484

0 commit comments

Comments
 (0)