Skip to content

Commit 795fbf2

Browse files
PijukatelPijukatel
authored
docs(openapi): Storage related fixes (#2372)
## Summary ### Dataset - name field can be null (unnamed storage) - POST `v2/datasets/:datasetId/items` can push both individual object or list of objects - Add missing 403 to POST `v2/datasets/:datasetId/items` - Extract and re-use pagination headers - Document HEAD `v2/datasets/:datasetId/items` that returns pagination headers ### KVS - name field can be null (unnamed storage) - content type of record can be `*/*`, not just `application/json` - Document `/v2/key-value-stores/:storeId/records` ### RQ - name field can be null (unnamed storage) - Extract and re-use shared properties - Request that are added can't have have ID (both single and batch) - deprecate `exclusiveStartId` - document `filter`, `cursor`, `nextCursor` and related pagination ### Others - Correct the OpenAPI specification version mentioned in docs - Add some undocumented alias PUT/POST endpoints - `v2/acts/:actorId/versions/:versionNumber` - `v2/acts/:actorId/versions/:versionNumber/env-vars/:envVarName` - `v2/key-value-stores/:storeId/records/:recordKey` ## Motivation - Solve OpenAPI validation errors ## Issues Partially implements: #2286
1 parent 8681998 commit 795fbf2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+708
-636
lines changed

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ Add code samples by creating files in `apify-api/openapi/code_samples/{javascrip
5353

5454
### OpenAPI specification changes
5555

56+
- Target OpenAPI specification version should be extracted from `/openapi/openapi.yaml`. All specification changes should be compliant with syntax for that specific OpenAPI specification version.
5657
- Prefer re-use of existing objects via `$ref` over duplication. Reusable components can be found in `/openapi/components`.
5758
- Components most suitable for re-use are:
5859
- Request parameters and path parameters defined in `/openapi/components/parameters`

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,7 @@ The API reference documentation at [docs.apify.com/api/v2](https://docs.apify.co
196196
197197
We use the following tools for API documentation:
198198
199-
- **[OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3)** - API specification format
199+
- **[OpenAPI 3.1.2](https://spec.openapis.org/oas/v3.1.2.html)** - API specification format
200200
- **[Redocly CLI](https://redocly.com/docs/cli/)** - Linting and validation of OpenAPI specs
201201
- **[`docusaurus-plugin-openapi-docs`](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs)** - Generates MDX docs from OpenAPI
202202
- **[`docusaurus-theme-openapi-docs`](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs)** - Renders API reference with interactive explorer

‎apify-api/openapi/components/headers/ApifyPaginationHeaders.yaml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
X-Apify-Pagination-Offset:
2+
description: The offset of the first item in the current page.
3+
content:
4+
text/plain:
5+
schema:
6+
type: string
7+
example: "0"
8+
X-Apify-Pagination-Limit:
9+
description: The maximum number of items returned per page.
10+
content:
11+
text/plain:
12+
schema:
13+
type: string
14+
example: "100"
15+
X-Apify-Pagination-Count:
16+
description: The number of items returned in the current page.
17+
content:
18+
text/plain:
19+
schema:
20+
type: string
21+
example: "100"
22+
X-Apify-Pagination-Total:
23+
description: The total number of items in the dataset.
24+
content:
25+
text/plain:
26+
schema:
27+
type: string
28+
example: "10204"

‎apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}@env-vars@{envVarName}put.yaml‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
shared: &shared
2+
tags:
3+
- Actors/Actor versions
4+
parameters:
5+
- $ref: "../../parameters/runAndBuildParameters.yaml#/actorId"
6+
- $ref: "../../parameters/runAndBuildParameters.yaml#/versionNumber"
7+
- name: envVarName
8+
in: path
9+
description: The name of the environment variable
10+
required: true
11+
style: simple
12+
schema:
13+
type: string
14+
example: MY_ENV_VAR
15+
requestBody:
16+
description: ""
17+
content:
18+
application/json:
19+
schema:
20+
$ref: ../../schemas/actors/EnvVar.yaml
21+
example:
22+
name: MY_ENV_VAR
23+
value: my-new-value
24+
isSecret: false
25+
required: true
26+
responses:
27+
"200":
28+
description: ""
29+
headers: {}
30+
content:
31+
application/json:
32+
schema:
33+
$ref: ../../schemas/actors/EnvVarResponse.yaml
34+
example:
35+
data:
36+
name: MY_ENV_VAR
37+
value: my-value
38+
isSecret: false
39+
"400":
40+
$ref: ../../responses/BadRequest.yaml
41+
"401":
42+
$ref: ../../responses/Unauthorized.yaml
43+
"403":
44+
$ref: ../../responses/Forbidden.yaml
45+
"404":
46+
description: Not found - the requested resource was not found.
47+
content:
48+
application/json:
49+
schema:
50+
oneOf:
51+
- $ref: "../../schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
52+
- $ref: "../../schemas/common/errors/ActorErrors.yaml#/ActorVersionNotFoundError"
53+
- $ref: "../../schemas/common/errors/EnvVariableErrors.yaml#/EnvironmentVariableNotFoundError"
54+
"405":
55+
$ref: ../../responses/MethodNotAllowed.yaml
56+
"413":
57+
$ref: ../../responses/PayloadTooLarge.yaml
58+
"415":
59+
$ref: ../../responses/UnsupportedMediaType.yaml
60+
"429":
61+
$ref: ../../responses/TooManyRequests.yaml
62+
deprecated: false
63+
x-py-parent: ActorEnvVarClientAsync
64+
x-py-name: update
65+
x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/ActorEnvVarClientAsync#update
66+
67+
put:
68+
<<: *shared
69+
summary: Update environment variable
70+
description: |
71+
Updates Actor environment variable using values specified by a [EnvVar
72+
object](#/reference/actors/environment-variable-object)
73+
passed as JSON in the POST payload.
74+
If the object does not define a specific property, its value will not be
75+
updated.
76+
77+
The request needs to specify the `Content-Type: application/json` HTTP
78+
header!
79+
80+
When providing your API authentication token, we recommend using the
81+
request's `Authorization` header, rather than the URL. ([More
82+
info](#/introduction/authentication)).
83+
84+
The response is the [EnvVar object](#/reference/actors/environment-variable-object) as returned by the
85+
[Get environment variable](#/reference/actors/environment-variable-object/get-environment-variable)
86+
endpoint.
87+
operationId: act_version_envVar_put
88+
x-legacy-doc-urls:
89+
- https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/update-environment-variable
90+
- https://docs.apify.com/api/v2#/reference/actors/update-environment-variable
91+
- https://docs.apify.com/api/v2#tag/ActorsEnvironment-variable-object/operation/act_version_envVar_put
92+
93+
post:
94+
<<: *shared
95+
summary: Update environment variable (POST)
96+
description: |
97+
Updates Actor environment variable using values specified by a [EnvVar
98+
object](#/reference/actors/environment-variable-object)
99+
passed as JSON in the POST payload.
100+
This endpoint is an alias for the [`PUT` update environment variable](#tag/ActorsEnvironment-variable-object/operation/act_version_envVar_put) method and behaves identically.
101+
operationId: act_version_envVar_post
102+
x-legacy-doc-urls:
103+
- https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/update-environment-variable
104+
- https://docs.apify.com/api/v2#/reference/actors/update-environment-variable
105+
- https://docs.apify.com/api/v2#tag/ActorsEnvironment-variable-object/operation/act_version_envVar_post

‎apify-api/openapi/components/objects/actors/acts@{actorId}@versions@{versionNumber}put.yaml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
shared: &shared
2+
tags:
3+
- Actors/Actor versions
4+
parameters:
5+
- $ref: "../../parameters/runAndBuildParameters.yaml#/actorId"
6+
- $ref: "../../parameters/runAndBuildParameters.yaml#/versionNumber"
7+
requestBody:
8+
description: ""
9+
content:
10+
application/json:
11+
schema:
12+
$ref: ../../schemas/actors/CreateOrUpdateVersionRequest.yaml
13+
example:
14+
versionNumber: "0.0"
15+
sourceType: SOURCE_FILES
16+
envVars:
17+
- name: DOMAIN
18+
value: http://example.com
19+
isSecret: false
20+
- name: SECRET_PASSWORD
21+
value: MyTopSecretPassword123
22+
isSecret: true
23+
applyEnvVarsToBuild: false
24+
buildTag: latest
25+
sourceFiles: []
26+
required: true
27+
responses:
28+
"200":
29+
description: ""
30+
headers: {}
31+
content:
32+
application/json:
33+
schema:
34+
$ref: ../../schemas/actors/VersionResponse.yaml
35+
"400":
36+
$ref: ../../responses/BadRequest.yaml
37+
"401":
38+
$ref: ../../responses/Unauthorized.yaml
39+
"403":
40+
$ref: ../../responses/Forbidden.yaml
41+
"404":
42+
description: Not found - the requested resource was not found.
43+
content:
44+
application/json:
45+
schema:
46+
$ref: "../../schemas/common/errors/ActorErrors.yaml#/ActorNotFoundError"
47+
"405":
48+
$ref: ../../responses/MethodNotAllowed.yaml
49+
"413":
50+
$ref: ../../responses/PayloadTooLarge.yaml
51+
"415":
52+
$ref: ../../responses/UnsupportedMediaType.yaml
53+
"429":
54+
$ref: ../../responses/TooManyRequests.yaml
55+
deprecated: false
56+
x-py-parent: ActorVersionClientAsync
57+
x-py-name: update
58+
x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/ActorVersionClientAsync#update
59+
60+
put:
61+
<<: *shared
62+
summary: Update version
63+
description: |
64+
Updates Actor version using values specified by a [Version object](#/reference/actors/version-object) passed as JSON in the POST payload.
65+
66+
If the object does not define a specific property, its value will not be
67+
updated.
68+
69+
The request needs to specify the `Content-Type: application/json` HTTP
70+
header!
71+
72+
When providing your API authentication token, we recommend using the
73+
request's `Authorization` header, rather than the URL. ([More
74+
info](#/introduction/authentication)).
75+
76+
The response is the [Version object](#/reference/actors/version-object) as
77+
returned by the [Get version](#/reference/actors/version-object/get-version) endpoint.
78+
operationId: act_version_put
79+
x-legacy-doc-urls:
80+
- https://docs.apify.com/api/v2#/reference/actors/version-object/update-version
81+
- https://docs.apify.com/api/v2#/reference/actors/update-version
82+
- https://docs.apify.com/api/v2#tag/ActorsVersion-object/operation/act_version_put
83+
84+
post:
85+
<<: *shared
86+
summary: Update version (POST)
87+
description: |
88+
Updates Actor version using values specified by a [Version object](#/reference/actors/version-object) passed as JSON in the POST payload.
89+
This endpoint is an alias for the [`PUT` update version](#tag/ActorsVersion-object/operation/act_version_put) method and behaves identically.
90+
operationId: act_version_post
91+
x-legacy-doc-urls:
92+
- https://docs.apify.com/api/v2#/reference/actors/version-object/update-version
93+
- https://docs.apify.com/api/v2#/reference/actors/update-version
94+
- https://docs.apify.com/api/v2#tag/ActorsVersion-object/operation/act_version_post

‎apify-api/openapi/components/objects/key-value-stores/key-value-stores@{storeId}@records@{recordKey}put.yaml‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
shared: &shared
2+
tags:
3+
- Storage/Key-value stores
4+
parameters:
5+
- $ref: "../../parameters/storageParameters.yaml#/storeId"
6+
- $ref: "../../parameters/storageParameters.yaml#/recordKey"
7+
- name: Content-Encoding
8+
in: header
9+
description: ""
10+
required: false
11+
style: simple
12+
schema:
13+
enum:
14+
- gzip
15+
- deflate
16+
- br
17+
type: string
18+
requestBody:
19+
description: ""
20+
content:
21+
application/json:
22+
schema:
23+
$ref: ../../schemas/key-value-stores/PutRecordRequest.yaml
24+
"*/*":
25+
schema: {}
26+
required: true
27+
responses:
28+
"201":
29+
description: ""
30+
headers:
31+
Location:
32+
content:
33+
text/plain:
34+
schema:
35+
type: string
36+
example: >-
37+
https://api.apify.com/v2/key-value-stores/WkzbQMuFYuamGv3YF/records/some-key
38+
content:
39+
application/json:
40+
schema:
41+
type: object
42+
example: {}
43+
"400":
44+
$ref: ../../responses/BadRequest.yaml
45+
"401":
46+
$ref: ../../responses/Unauthorized.yaml
47+
"403":
48+
$ref: ../../responses/Forbidden.yaml
49+
"405":
50+
$ref: ../../responses/MethodNotAllowed.yaml
51+
"413":
52+
$ref: ../../responses/PayloadTooLarge.yaml
53+
"415":
54+
$ref: ../../responses/UnsupportedMediaType.yaml
55+
"429":
56+
$ref: ../../responses/TooManyRequests.yaml
57+
deprecated: false
58+
x-js-parent: KeyValueStoreClient
59+
x-js-name: setRecord
60+
x-js-doc-url: https://docs.apify.com/api/client/js/reference/class/KeyValueStoreClient#setRecord
61+
x-py-parent: KeyValueStoreClientAsync
62+
x-py-name: set_record
63+
x-py-doc-url: https://docs.apify.com/api/client/python/reference/class/KeyValueStoreClientAsync#set_record
64+
65+
put:
66+
<<: *shared
67+
summary: Store record
68+
description: |
69+
Stores a value under a specific key to the key-value store.
70+
71+
The value is passed as the PUT payload and it is stored with a MIME content
72+
type defined by the `Content-Type` header and with encoding defined by the
73+
`Content-Encoding` header.
74+
75+
To save bandwidth, storage, and speed up your upload, send the request
76+
payload compressed with Gzip compression and add the `Content-Encoding: gzip`
77+
header. It is possible to set up another compression type with `Content-Encoding`
78+
request header.
79+
80+
Below is a list of supported `Content-Encoding` types.
81+
82+
* Gzip compression: `Content-Encoding: gzip`
83+
* Deflate compression: `Content-Encoding: deflate`
84+
* Brotli compression: `Content-Encoding: br`
85+
operationId: keyValueStore_record_put
86+
x-legacy-doc-urls:
87+
- https://docs.apify.com/api/v2#/reference/key-value-stores/record/put-record
88+
- https://docs.apify.com/api/v2#/reference/key-value-stores/put-record
89+
- https://docs.apify.com/api/v2#tag/Key-value-storesRecord/operation/keyValueStore_record_put
90+
91+
post:
92+
<<: *shared
93+
summary: Store record (POST)
94+
description: |
95+
Stores a value under a specific key to the key-value store.
96+
This endpoint is an alias for the [`PUT` record](#tag/Key-value-storesRecord/operation/keyValueStore_record_put) method and behaves identically.
97+
operationId: keyValueStore_record_post
98+
x-legacy-doc-urls:
99+
- https://docs.apify.com/api/v2#/reference/key-value-stores/record/put-record
100+
- https://docs.apify.com/api/v2#/reference/key-value-stores/put-record
101+
- https://docs.apify.com/api/v2#tag/Key-value-storesRecord/operation/keyValueStore_record_post

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ properties:
1414
type: string
1515
examples: [WkzbQMuFYuamGv3YF]
1616
name:
17-
type: string
17+
type: [string, "null"]
1818
examples: [d7b9MDYsbtX5L7XAj]
1919
userId:
2020
type: string

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ title: UpdateDatasetRequest
22
type: object
33
properties:
44
name:
5-
type: string
5+
type: [string, "null"]
66
generalAccess:
77
$ref: ../common/GeneralAccess.yaml
88
example:

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ properties:
1010
type: string
1111
examples: [WkzbQMuFYuamGv3YF]
1212
name:
13-
type: string
13+
type: [string, "null"]
1414
examples: [d7b9MDYsbtX5L7XAj]
1515
userId:
1616
type: [string, "null"]

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,11 @@ properties:
1818
type: integer
1919
examples: [2]
2020
exclusiveStartKey:
21-
type: string
21+
type: [string, "null"]
2222
examples: [some-key]
2323
isTruncated:
2424
type: boolean
2525
examples: [true]
2626
nextExclusiveStartKey:
27-
type: string
27+
type: [string, "null"]
2828
examples: [third-key]

0 commit comments

Comments
 (0)