Skip to content

Commit 42b0e5e

Browse files
PijukatelPijukatel
authored
docs(openapi): Improve storage endpoints (#2314)
## Summary - Create reusable error response schemas - Use granular 404 errors - Auto-generate examples if possible - Move unique examples closer to the schema definition - Delete duplicate examples - Extract and re-use non-unique parameters - Fix non-working API docs client examples: - https://docs.apify.com/api/v2/request-queue-requests-batch-delete - https://docs.apify.com/api/v2/key-value-store-record-put ## Motivation - Preparation for adding undocumented re-dispatch endpoints, which will re-use the error schemas and parameters. - Properly document different 404 errors returnable by the endpoint. This will give the user a better idea about potential failures. - Make the specification more maintainable ## Issues Partially implements: #2286
1 parent 9dd34f4 commit 42b0e5e

32 files changed

+656
-1114
lines changed

‎apify-api/openapi/components/parameters/PaginationParameters.yaml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
Offset:
2+
name: offset
3+
in: query
4+
description: |
5+
Number of items that should be skipped at the start. The default value is `0`.
6+
style: form
7+
explode: true
8+
schema:
9+
type: number
10+
format: double
11+
example: 0
12+
13+
Limit:
14+
name: limit
15+
in: query
16+
description: |
17+
Maximum number of items to return. The default value as well as the maximum is `1000`.
18+
style: form
19+
explode: true
20+
schema:
21+
type: number
22+
format: double
23+
example: 1000
24+
25+
Desc:
26+
name: desc
27+
in: query
28+
description: |
29+
If `true` or `1` then the results are returned in descending order.
30+
By default, they are sorted in ascending order.
31+
style: form
32+
explode: true
33+
schema:
34+
type: boolean
35+
example: true
36+
37+
Unnamed:
38+
name: unnamed
39+
in: query
40+
description: |
41+
If `true` or `1` then all the storages are returned. By default, only
42+
named storages are returned.
43+
style: form
44+
explode: true
45+
schema:
46+
type: boolean
47+
example: true

‎apify-api/openapi/components/parameters/StorageParameters.yaml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
DatasetId:
2+
name: datasetId
3+
in: path
4+
description: Dataset ID or `username~dataset-name`.
5+
required: true
6+
style: simple
7+
schema:
8+
type: string
9+
example: WkzbQMuFYuamGv3YF
10+
11+
StoreId:
12+
name: storeId
13+
in: path
14+
description: Key-value store ID or `username~store-name`.
15+
required: true
16+
style: simple
17+
schema:
18+
type: string
19+
example: WkzbQMuFYuamGv3YF
20+
21+
RecordKey:
22+
name: recordKey
23+
in: path
24+
description: Key of the record.
25+
required: true
26+
style: simple
27+
schema:
28+
type: string
29+
example: someKey
30+
31+
QueueId:
32+
name: queueId
33+
in: path
34+
description: Queue ID or `username~queue-name`.
35+
required: true
36+
style: simple
37+
schema:
38+
type: string
39+
example: WkzbQMuFYuamGv3YF
40+
41+
RequestId:
42+
name: requestId
43+
in: path
44+
description: Request ID.
45+
required: true
46+
style: simple
47+
schema:
48+
type: string
49+
example: xpsmkDlspokDSmklS
50+
51+
ClientKey:
52+
name: clientKey
53+
in: query
54+
description: |
55+
A unique identifier of the client accessing the request queue. It must
56+
be a string between 1 and 32 characters long. This identifier is used to
57+
determine whether the queue was accessed by multiple clients. If
58+
`clientKey` is not provided,
59+
the system considers this API call to come from a new client. For
60+
details, see the `hadMultipleClients` field returned by the [Get
61+
head](#/reference/request-queues/queue-head) operation.
62+
style: form
63+
explode: true
64+
schema:
65+
type: string
66+
example: client-abc
67+
68+
ClientKeyLock:
69+
name: clientKey
70+
in: query
71+
description: |
72+
A unique identifier of the client accessing the request queue. It must
73+
be a string between 1 and 32 characters long. This identifier is used for locking
74+
and unlocking requests. You can delete or prolong the lock only for requests that were locked by the same
75+
client key or from the same Actor run.
76+
style: form
77+
explode: true
78+
schema:
79+
type: string
80+
example: client-abc
81+
82+
LockSecs:
83+
name: lockSecs
84+
in: query
85+
description: How long the requests will be locked for (in seconds).
86+
required: true
87+
style: form
88+
explode: true
89+
schema:
90+
type: number
91+
format: double
92+
example: 60
93+
94+
Forefront:
95+
name: forefront
96+
in: query
97+
description: |
98+
Determines if request should be added to the head of the queue or to the
99+
end. Default value is `false` (end of queue).
100+
style: form
101+
explode: true
102+
schema:
103+
type: string
104+
example: "false"
105+
106+
Signature:
107+
name: signature
108+
in: query
109+
description: Signature used for the access.
110+
required: false
111+
style: form
112+
schema:
113+
type: string
114+
example: 2wTI46Bg8qWQrV7tavlPI

‎apify-api/openapi/components/schemas/common/PaginationResponse.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ properties:
1212
type: integer
1313
description: The total number of items available across all pages.
1414
minimum: 0
15-
examples: [2]
15+
examples: [1]
1616
offset:
1717
type: integer
1818
description: The starting position for this page of results.
@@ -31,4 +31,4 @@ properties:
3131
type: integer
3232
description: The number of items returned in this response.
3333
minimum: 0
34-
examples: [2]
34+
examples: [1]

‎apify-api/openapi/components/schemas/common/errors/StorageErrors.yaml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
DatasetNotFoundError:
2+
type: object
3+
properties:
4+
error:
5+
type: object
6+
properties:
7+
type:
8+
type: string
9+
enum: [record-not-found]
10+
message:
11+
type: string
12+
example: Dataset was not found
13+
14+
KeyValueStoreNotFoundError:
15+
type: object
16+
properties:
17+
error:
18+
type: object
19+
properties:
20+
type:
21+
type: string
22+
enum: [record-not-found]
23+
message:
24+
type: string
25+
example: Key-value Store was not found
26+
27+
RequestQueueNotFoundError:
28+
type: object
29+
properties:
30+
error:
31+
type: object
32+
properties:
33+
type:
34+
type: string
35+
enum: [record-not-found]
36+
message:
37+
type: string
38+
example: Request Queue was not found
39+
40+
RecordNotFoundError:
41+
type: object
42+
properties:
43+
error:
44+
type: object
45+
properties:
46+
type:
47+
type: string
48+
enum: [record-not-found]
49+
message:
50+
type: string
51+
example: Record was not found
52+
53+
RequestNotFoundError:
54+
type: object
55+
properties:
56+
error:
57+
type: object
58+
properties:
59+
type:
60+
type: string
61+
enum: [record-not-found]
62+
message:
63+
type: string
64+
example: Request was not found
65+
66+
RequestIdInvalidError:
67+
type: object
68+
properties:
69+
error:
70+
type: object
71+
properties:
72+
type:
73+
type: string
74+
enum: [request-id-invalid]
75+
message:
76+
type: string
77+
example: Request ID does not correspond to uniqueKey

‎apify-api/openapi/components/schemas/datasets/DatasetListItem.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,5 +39,7 @@ properties:
3939
examples: [5]
4040
actId:
4141
type: [string, "null"]
42+
examples: [zdc3Pyhyz3m8vjDeM]
4243
actRunId:
4344
type: [string, "null"]
45+
examples: [HG7ML7M8z78YcAPEB]

‎apify-api/openapi/components/schemas/datasets/DatasetStatistics.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,10 @@ properties:
66
additionalProperties:
77
$ref: ./DatasetFieldStatistics.yaml
88
description: When you configure the dataset [fields schema](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation), we measure the statistics such as `min`, `max`, `nullCount` and `emptyCount` for each field. This property provides statistics for each field from dataset fields schema. <br/></br>See dataset field statistics [documentation](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema/validation#dataset-field-statistics) for more information.
9+
example:
10+
fieldStatistics:
11+
name:
12+
nullCount: 122
13+
price:
14+
min: 59
15+
max: 89

‎apify-api/openapi/components/schemas/datasets/PutItemResponseError.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,17 @@ type: object
55
properties:
66
error:
77
$ref: ./DatasetSchemaValidationError.yaml
8+
example:
9+
error:
10+
type: schema-validation-error
11+
message: Schema validation failed
12+
data:
13+
invalidItems:
14+
- itemPosition: 2
15+
validationErrors:
16+
- instancePath: /1/stringField
17+
schemaPath: /items/properties/stringField/type
18+
keyword: type
19+
params:
20+
type: string
21+
message: must be string

‎apify-api/openapi/components/schemas/key-value-stores/ListOfKeyValueStoresResponse.yaml‎

Lines changed: 1 addition & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,4 @@ required:
44
- data
55
properties:
66
data:
7-
allOf:
8-
- $ref: ./ListOfKeyValueStores.yaml
9-
- example:
10-
items:
11-
- id: WkzbQMuFYuamGv3YF
12-
name: d7b9MDYsbtX5L7XAj
13-
userId: BPWDBd7Z9c746JAnF
14-
username: janedoe
15-
createdAt: "2019-12-12T07:34:14.202Z"
16-
modifiedAt: "2019-12-13T08:36:13.202Z"
17-
accessedAt: "2019-12-14T08:36:13.202Z"
18-
actId: null
19-
actRunId: null
20-
- id: YiKoxjkaS9gjGTqhF
21-
name: eshop-items
22-
userId: BPWDBd7Z9c746JAnF
23-
username: janedoe
24-
createdAt: "2019-12-12T07:34:14.202Z"
25-
modifiedAt: "2019-12-13T08:36:13.202Z"
26-
accessedAt: "2019-12-14T08:36:13.202Z"
27-
actId: null
28-
actRunId: null
7+
$ref: ./ListOfKeyValueStores.yaml

‎apify-api/openapi/components/schemas/key-value-stores/ListOfKeysResponse.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,17 @@ type: object
55
properties:
66
data:
77
$ref: ./ListOfKeys.yaml
8+
example:
9+
data:
10+
items:
11+
- key: second-key
12+
size: 36
13+
recordPublicUrl: https://api.apify.com/v2/key-value-stores/WkzbQMuFYuamGv3YF/records/second-key?signature=abc123
14+
- key: third-key
15+
size: 128
16+
recordPublicUrl: https://api.apify.com/v2/key-value-stores/WkzbQMuFYuamGv3YF/records/third-key?signature=abc123
17+
count: 2
18+
limit: 2
19+
exclusiveStartKey: some-key
20+
isTruncated: true
21+
nextExclusiveStartKey: third-key

‎apify-api/openapi/components/schemas/request-queues/BatchAddResponse.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,14 @@ type: object
66
properties:
77
data:
88
$ref: ./BatchAddResult.yaml
9+
example:
10+
data:
11+
processedRequests:
12+
- requestId: YiKoxjkaS9gjGTqhF
13+
uniqueKey: "http://example.com"
14+
wasAlreadyPresent: true
15+
wasAlreadyHandled: false
16+
unprocessedRequests:
17+
- uniqueKey: http://example.com/2
18+
url: http://example.com/2
19+
method: GET

0 commit comments

Comments
 (0)