From 8c7e2595ced910187128761c01dc8878a2a0f4eb Mon Sep 17 00:00:00 2001 From: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com> Date: Wed, 22 Jan 2025 15:45:14 +0100 Subject: [PATCH] feat(api): added openapi endpoints (#1422) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Recently, we introduced two new endpoints that return the OpenAPI specification: - `/acts//builds//openapi-specification` - `/actor-builds//openapi-specification` **This PR updates the documentation to include these endpoints.** @TC-MO Let me, please, know if you think we should add any additional information 🙏 --- .../actor-builds/GetOpenApiResponse.yaml | 348 ++++++++++++++++++ apify-api/openapi/components/tags.yaml | 18 + .../openapi/components/x-tag-groups.yaml | 2 + apify-api/openapi/openapi.yaml | 4 + ...uilds@{buildId}@openapi-specification.yaml | 30 ++ ...uilds@{buildId}@openapi-specification.yaml | 40 ++ 6 files changed, 442 insertions(+) create mode 100644 apify-api/openapi/components/schemas/actor-builds/GetOpenApiResponse.yaml create mode 100644 apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi-specification.yaml create mode 100644 apify-api/openapi/paths/actors/acts@{actorId}@builds@{buildId}@openapi-specification.yaml diff --git a/apify-api/openapi/components/schemas/actor-builds/GetOpenApiResponse.yaml b/apify-api/openapi/components/schemas/actor-builds/GetOpenApiResponse.yaml new file mode 100644 index 000000000..a5a159db6 --- /dev/null +++ b/apify-api/openapi/components/schemas/actor-builds/GetOpenApiResponse.yaml @@ -0,0 +1,348 @@ +title: GetOpenApiResponse +type: object +properties: + openapi: + type: string + example: 3.0.1 + info: + type: object + properties: + title: + type: string + example: Your Magic Actor + version: + type: string + example: '1.0' + x-build-id: + type: string + example: 'ID of build' + servers: + type: array + items: + type: object + properties: + url: + type: string + example: https://api.apify.com/v2 + paths: + type: object + properties: + /acts/~/run-sync-get-dataset-items: + type: object + properties: + post: + type: object + properties: + operationId: + type: string + example: run-sync-get-dataset-items + x-openai-isConsequential: + type: boolean + example: false + summary: + type: string + example: Executes an Actor, waits for its completion, and returns Actor's dataset items in response. + tags: + type: array + items: + type: string + example: ['Run Actor'] + requestBody: + type: object + properties: + required: + type: boolean + example: true + content: + type: object + properties: + application/json: + type: object + properties: + schema: + type: object + properties: + $ref: + type: string + example: '#/components/schemas/inputSchema' + parameters: + type: array + items: + type: object + properties: + name: + type: string + example: token + in: + type: string + example: query + required: + type: boolean + example: true + schema: + type: object + properties: + type: + type: string + example: string + description: + type: string + example: Enter your Apify token here + responses: + type: object + properties: + '200': + type: object + properties: + description: + type: string + example: OK + /acts/~/runs: + type: object + properties: + post: + type: object + properties: + operationId: + type: string + example: runs + x-openai-isConsequential: + type: boolean + example: false + summary: + type: string + example: Executes an Actor and returns information about the initiated run in response. + tags: + type: array + items: + type: string + example: ['Run Actor'] + requestBody: + type: object + properties: + required: + type: boolean + example: true + content: + type: object + properties: + application/json: + type: object + properties: + schema: + type: object + properties: + $ref: + type: string + example: '#/components/schemas/inputSchema' + parameters: + type: array + items: + type: object + properties: + name: + type: string + in: + type: string + example: query + required: + type: boolean + schema: + type: object + properties: + type: + type: string + description: + type: string + responses: + type: object + properties: + '200': + type: object + properties: + description: + type: string + example: OK + content: + type: object + properties: + application/json: + type: object + properties: + schema: + type: object + properties: + $ref: + type: string + example: '#/components/schemas/runsResponseSchema' + /acts/~/run-sync: + type: object + properties: + post: + type: object + properties: + operationId: + type: string + example: run-sync + x-openai-isConsequential: + type: boolean + example: false + summary: + type: string + example: Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response. + tags: + type: array + items: + type: string + example: ['Run Actor'] + requestBody: + type: object + properties: + required: + type: boolean + example: true + content: + type: object + properties: + application/json: + type: object + properties: + schema: + type: object + properties: + $ref: + type: string + example: '#/components/schemas/inputSchema' + parameters: + type: array + items: + type: object + properties: + name: + type: string + in: + type: string + example: query + required: + type: boolean + schema: + type: object + properties: + type: + type: string + description: + type: string + responses: + type: object + properties: + '200': + type: object + properties: + description: + type: string + example: OK + components: + type: object + properties: + schemas: + type: object + properties: + inputSchema: + type: object + properties: + type: + type: string + example: object + runsResponseSchema: + type: object + properties: + type: + type: string + example: object + properties: + type: object + properties: + data: + type: object + properties: + type: + type: string + example: object + properties: + type: object + properties: + id: + type: object + properties: + type: + type: string + example: string + actId: + type: object + properties: + type: + type: string + example: string + userId: + type: object + properties: + type: + type: string + example: string + startedAt: + type: object + properties: + type: + type: string + example: string + format: + type: string + example: date-time + example: + type: string + example: '2025-01-08T00:00:00.000Z' + finishedAt: + type: object + properties: + type: + type: string + example: string + format: + type: string + example: date-time + example: + type: string + example: '2025-01-08T00:00:00.000Z' + status: + type: object + properties: + type: + type: string + example: string + example: + type: string + example: 'READY' + meta: + type: object + properties: + type: + type: string + example: object + properties: + type: object + properties: + origin: + type: object + properties: + type: + type: string + example: string + example: + type: string + example: 'API' + userAgent: + type: object + properties: + type: + type: string + example: string diff --git a/apify-api/openapi/components/tags.yaml b/apify-api/openapi/components/tags.yaml index baa466a58..317b1775b 100644 --- a/apify-api/openapi/components/tags.yaml +++ b/apify-api/openapi/components/tags.yaml @@ -251,6 +251,15 @@ ``` In order to save new items to the dataset, send HTTP POST request with JSON payload to the same URL. +- name: Actors/Get OpenAPI specification + x-displayName: Get OpenAPI specification + x-parent-tag-name: Actors + x-trait: 'true' + description: | + Get the OpenAPI specification for Actor builds. Two similar endpoints are available: + + - [First endpoint](/api/v2/act-openapi-specification-get): Requires both `actorId` and `buildId`. Use `default` as the `buildId` to get the OpenAPI schema for the default Actor build. + - [Second endpoint](/api/v2/actor-build-openapi-specification-get): Requires only `buildId`. - name: Actor tasks x-displayName: Actor tasks x-legacy-doc-urls: @@ -548,6 +557,15 @@ - '#tag/Actor-buildsBuild-log' x-trait: 'true' description: Check out [Logs](#/reference/logs) for full reference. +- name: Actor builds/Get OpenAPI specification + x-displayName: Get OpenAPI specification + x-parent-tag-name: Actor builds + x-trait: 'true' + description: | + Get the OpenAPI specification for Actor builds. Two similar endpoints are available: + + - [First endpoint](/api/v2/act-openapi-specification-get): Requires both `actorId` and `buildId`. Use `default` as the `buildId` to get the OpenAPI schema for the default Actor build. + - [Second endpoint](/api/v2/actor-build-openapi-specification-get): Requires only `buildId`. - name: Key-value stores x-displayName: Key-value stores x-legacy-doc-urls: diff --git a/apify-api/openapi/components/x-tag-groups.yaml b/apify-api/openapi/components/x-tag-groups.yaml index 9a85e48d2..a9abef590 100644 --- a/apify-api/openapi/components/x-tag-groups.yaml +++ b/apify-api/openapi/components/x-tag-groups.yaml @@ -19,6 +19,7 @@ - Actors/Metamorph run - Actors/Resurrect run - Actors/Last run object and its storages + - Actors/Get OpenAPI specification - name: Actor tasks tags: - Actor tasks @@ -50,6 +51,7 @@ - Actor builds/Delete build - Actor builds/Abort build - Actor builds/Build log + - Actor builds/Get OpenAPI specification - name: Key-value stores tags: - Key-value stores diff --git a/apify-api/openapi/openapi.yaml b/apify-api/openapi/openapi.yaml index a0f3b23bf..532ddfcf5 100644 --- a/apify-api/openapi/openapi.yaml +++ b/apify-api/openapi/openapi.yaml @@ -501,6 +501,8 @@ paths: $ref: 'paths/actors/acts@{actorId}@builds@{buildId}.yaml' '/v2/acts/{actorId}/builds/{buildId}/abort': $ref: 'paths/actors/acts@{actorId}@builds@{buildId}@abort.yaml' + '/v2/acts/{actorId}/builds/{buildId}/openapi-specification': + $ref: 'paths/actors/acts@{actorId}@builds@{buildId}@openapi-specification.yaml' '/v2/acts/{actorId}/runs': $ref: 'paths/actors/acts@{actorId}@runs.yaml' '/v2/acts/{actorId}/run-sync': @@ -553,6 +555,8 @@ paths: $ref: 'paths/actor-builds/actor-builds@{buildId}@abort.yaml' '/v2/actor-builds/{buildId}/log': $ref: 'paths/actor-builds/actor-builds@{buildId}@log.yaml' + '/v2/actor-builds/{buildId}/openapi-specification': + $ref: 'paths/actor-builds/actor-builds@{buildId}@openapi-specification.yaml' /v2/key-value-stores: $ref: paths/key-value-stores/key-value-stores.yaml '/v2/key-value-stores/{storeId}': diff --git a/apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi-specification.yaml b/apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi-specification.yaml new file mode 100644 index 000000000..da6fb545c --- /dev/null +++ b/apify-api/openapi/paths/actor-builds/actor-builds@{buildId}@openapi-specification.yaml @@ -0,0 +1,30 @@ +get: + tags: + - Actor builds/Get OpenAPI specification + summary: Get OpenAPI specification + description: | + Get the OpenAPI specification for a specific Actor build. + Authentication is based on the build's unique ID. No authentication token is required. + + **Note**: You can also use the `/api/v2/act-openapi-specification-get` endpoint to get the OpenAPI specification for a build. + operationId: actorBuild_openapiSpecification_get + security: + - apiKeyActorBuilds: [] + - httpBearerActorBuilds: [] + parameters: + - name: buildId + in: path + description: ID of the build you want to get, found in the build's `Info` tab. + required: true + style: simple + schema: + type: string + example: soSkq9ekdmfOslopH + responses: + '200': + description: '' + headers: {} + content: + application/json: + schema: + $ref: '../../components/schemas/actor-builds/GetOpenApiResponse.yaml' diff --git a/apify-api/openapi/paths/actors/acts@{actorId}@builds@{buildId}@openapi-specification.yaml b/apify-api/openapi/paths/actors/acts@{actorId}@builds@{buildId}@openapi-specification.yaml new file mode 100644 index 000000000..6a929cfcd --- /dev/null +++ b/apify-api/openapi/paths/actors/acts@{actorId}@builds@{buildId}@openapi-specification.yaml @@ -0,0 +1,40 @@ +get: + tags: + - Actors/Get OpenAPI specification + summary: Get OpenAPI specification + description: | + Get the OpenAPI specification for a specific Actor build. + + To fetch the default Actor build, simply pass `default` as the `buildId`. + Authentication is based on the build's unique ID. No authentication token is required. + + **Note**: You can also use the `/api/v2/actor-build-openapi-specification-get` endpoint to get the OpenAPI specification for a build. + operationId: act_openapiSpecification_get + security: + - apiKeyActorBuilds: [] + - httpBearerActorBuilds: [] + parameters: + - name: actorId + in: path + description: Actor ID or a tilde-separated owner's username and Actor name. + required: true + style: simple + schema: + type: string + example: janedoe~my-actor + - name: buildId + in: path + description: ID of the build you want to get, found in the build's `Info` tab. Pass `default` for default Actor build. + required: true + style: simple + schema: + type: string + example: soSkq9ekdmfOslopH + responses: + '200': + description: '' + headers: {} + content: + application/json: + schema: + $ref: '../../components/schemas/actor-builds/GetOpenApiResponse.yaml'