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

API Guideline - Return list of API resources under a results array #138

Merged
merged 8 commits into from
Jul 7, 2022
Merged

API Guideline - Return list of API resources under a results array #138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
fad6b2a
Place list of documents under a results array on /documents
gmourier Mar 31, 2022
f831bb1
Add results array for indexes object list
gmourier Apr 6, 2022
4e09a60
Add the future of indexes pagination
gmourier Apr 6, 2022
bb343e6
Update open-api.yml
gmourier Apr 6, 2022
1a2f96f
Fix typo
gmourier Apr 6, 2022
893aaed
Apply suggestions from code review
gmourier Apr 11, 2022
d324feb
Add offset/limit pagination for indexes and API keys
gmourier Apr 13, 2022
b7d7e2b
Try to add multipe refs to a response object
gmourier May 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 97 additions & 28 deletions open-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,14 @@ components:
type: integer
description: Limit given for the query. If limit is not provided as a query parameter, this parameter displays the default limit value.
example: 10
offset:
type: integer
description: Offset given for the query. If offset is not provided as a query parameter, this parameter displays the default offset value.
example: 0
total:
type: integer
description: Total number of browsable results using offset/limit parameters for the given resource.
example: 50
from:
type: integer
description: The first task uid returned.
Expand Down Expand Up @@ -84,7 +92,7 @@ components:
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: '1993-01-01'
release_date: 725846400
description: 'A document made of attribute. The maximum number of attribute for a document is 65,535.'
matchesPosition:
type: object
Expand All @@ -106,13 +114,13 @@ components:
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: '1993-01-01'
release_date: 725846400
_formatted:
id: 25684
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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>.'
release_date: '1993-01-01'
release_date: 725846400
_matchesPosition:
overview:
- start: 49
Expand All @@ -124,13 +132,13 @@ components:
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: '1993-01-01'
release_date: 725846400
_formatted:
id: 25684
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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>.'
release_date: '1993-01-01'
release_date: 725846400
_matchesPosition:
overview:
- start: 49
Expand Down Expand Up @@ -675,14 +683,14 @@ components:
limit:
name: limit
in: query
description: Maximum number of documents to return.
description: Maximum number of results to return.
schema:
type: number
default: 20
offset:
name: offset
in: query
description: Number of documents to skip.
description: Number of results to skip.
schema:
type: number
default: 0
Expand Down Expand Up @@ -1014,19 +1022,40 @@ paths:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/index'
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/index'
limit:
$ref: '#/components/schemas/limit'
offset:
$ref: '#/components/schemas/offset'
total:
$ref: '#/components/schemas/total'
required:
- results
- limit
- offset
- total
examples:
Example:
value:
- uid: movies
name: movies
primaryKey: movie_id
createdAt: '2019-11-20T09:40:33.711324Z'
updatedAt: '2019-11-20T09:40:33.711324Z'
results:
- uid: movies
name: movies
primaryKey: movie_id
createdAt: '2019-11-20T09:40:33.711324Z'
updatedAt: '2019-11-20T09:40:33.711324Z'
limit: 1
offset: 0
total: 1
'401':
$ref: '#/components/responses/401'
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
post:
operationId: indexes.create
summary: Create Index
Expand Down Expand Up @@ -1192,17 +1221,40 @@ paths:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/document'
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/document'
limit:
$ref: '#/components/schemas/limit'
offset:
$ref: '#/components/schemas/offset'
total:
$ref: '#/components/schemas/total'
required:
- results
- limit
- offset
- total
examples:
Example:
value:
- id: 25684
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: '1993-01-01'
results:
- id: 25684
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: 725846400
- id: 45881
title: The Bridge of San Luis Rey
poster: 'https://image.tmdb.org/t/p/w500/4X7quIcdkc24Cveg5XdpfRqxtYA.jpg'
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."
release_date: 1072915200
limit: 20
offset: 0
total: 2
'401':
$ref: '#/components/responses/401'
'404':
Expand Down Expand Up @@ -1290,7 +1342,7 @@ paths:
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: '1993-01-01'
release_date: 725846400
description: ''
responses:
'202':
Expand Down Expand Up @@ -1446,13 +1498,13 @@ paths:
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: '1993-01-01'
release_date: 725846400
_formatted:
id: 25684
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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>.'
release_date: '1993-01-01'
release_date: 725846400
_matchesPosition:
overview:
- start: 49
Expand Down Expand Up @@ -1588,13 +1640,13 @@ paths:
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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.'
release_date: '1993-01-01'
release_date: 725846400
_formatted:
id: 25684
title: American Ninja 5
poster: 'https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg'
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>.'
release_date: '1993-01-01'
release_date: 725846400
_matchesPosition:
overview:
- start: 49
Expand Down Expand Up @@ -2502,6 +2554,17 @@ paths:
type: array
items:
$ref: '#/components/schemas/key'
limit:
$ref: '#/components/schemas/limit'
offset:
$ref: '#/components/schemas/offset'
total:
$ref: '#/components/schemas/total'
required:
- results
- limit
- offset
- total
examples:
example-1:
value:
Expand All @@ -2515,8 +2578,14 @@ paths:
expiresAt: '2022-11-12T10:00:00Z'
createdAt: '2021-11-12T10:00:00Z'
updatedAt: '2021-11-12T10:00:00Z'
limit: 20
offset: 0
total: 1
'401':
$ref: '#/components/responses/401'
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
'/keys/{key}':
get:
summary: Get an API key
Expand Down
66 changes: 64 additions & 2 deletions text/0085-api-keys.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -367,8 +367,67 @@ Only the master key allows managing the API keys.
```
"Authorization: Bearer :masterKey"
```
##### Query Parameters

##### Response
| Field | Type | Required |
|--------------------------|--------------------------|----------|
| `offset` | Integer / `null` | false |
| `limit` | Integer / `null` | false |

###### `offset`

- Type: Integer
- Required: False
- Default: `0`

Sets the starting point in the results, effectively skipping over a given number of API keys.

###### `limit`

- Type: Integer
- Required: False
- Default: `20`

Sets the maximum number of documents to be returned by the current request.

##### Response Definition

| Field | Type | Required |
|--------------------------|--------------------------|----------|
| `result` | Array[Key] | true |
| `offset` | Integer | true |
| `limit` | Integer | true |
| `total` | Integer | true |

###### `results`

- Type: Array[Key]
- Required: True

An array containing the fetched API keys.

###### `offset`

- Type: Integer
- Required: True

Gives the `offset` parameter used for the query.

###### `limit`

- Type: Integer
- Required: True

Gives the `limit` parameter used for the query.

###### `total`

- Type: Integer
- Required: True

Gives the total number of API keys that can be browsed.

###### Example

`200 Success`

Expand Down Expand Up @@ -416,7 +475,10 @@ Only the master key allows managing the API keys.
"createdAt": "2021-08-11T10:00:00Z",
"updatedAt": "2021-08-11T10:00:00Z"
}
]
],
"offset": 0,
"limit": 20,
"total": 3
}
```

Expand Down
Loading