Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: fix Actor capitalization throughout open api docs #1331

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

docs: fix Actor capitalization throughout open api docs #1331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7b110ab
docs: fix Actor capitalization throughout open api docs
TC-MO Dec 9, 2024
65f4729
fix wrongly rendered backticks
TC-MO Dec 9, 2024
54cf70e
revert changes done to tags
TC-MO Dec 9, 2024
8234151
fix tag in OpenAPI specs
TC-MO Dec 10, 2024
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
4 changes: 2 additions & 2 deletions apify-api/openapi/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ info:

To use your token in a request, either:

- Add the token to your request's `Authorization` header as `Bearer
<token>`.
- Add the token to your request's `Authorization` header as <code>Bearer
&lt;token&gt;</code>.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this written by hand? Are you aware of the HTML entities and the HTML tags instead of Markdown backticks?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, because for some reason regular backticks are not working in new API docs check the screenshot from current version

it looks fine on Redoc version
image

but this is how it looks currently on the new API docs
image

I tested this locally and it changed to backticks locally so I hope the same will happen on prod

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll have a look, next time ping me with such issues instead of going with some workaround, I hope we can find a way to make this work without any changes, since the workaround is ugly at best :]

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this seems to be a problem with redoc, it escapes HTML inside code blocks for some weird reason, and apparently, it's like that for the last 7 years (Redocly/redoc@fef9ec4)

the commit description says if lang is not specified, maybe we can just specify a language somehow, but I don't see a way to do that with inline code blocks

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm but on redoc API it is rederered correctly, the issue was in new API docs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, its their quirk, it makes no sense to escape anything inside code blocks. I think they just solve things on wrong level.

E.g., `Authorization: Bearer xxxxxxx`.
[More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).
(Recommended).
Expand Down
2 changes: 1 addition & 1 deletion apify-api/openapi/paths/actor-runs/actor-runs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ get:
summary: Get user runs list
description: |
Gets a list of all runs for a user. The response is a list of objects, where
each object contains basic information about a single actor run.
each object contains basic information about a single Actor run.

The endpoint supports pagination using the `limit` and `offset` parameters
and it will not return more than 1000 array elements.
Expand Down
14 changes: 7 additions & 7 deletions apify-api/openapi/paths/actor-runs/actor-runs@{runId}.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ get:
The endpoints accept the same HTTP methods and query parameters as
the respective storage endpoints.

The base path that represents the actor run object is:
The base path that represents the Actor run object is:

`/v2/actor-runs/{runId}{?token}`

In order to access the default storages of the actor run, i.e. log,
In order to access the default storages of the Actor run, i.e. log,
key-value store, dataset and request queue, use the following endpoints:

* `/v2/actor-runs/{runId}/log{?token}`
Expand Down Expand Up @@ -55,7 +55,7 @@ get:
* `/v2/actor-runs/{runId}/request-queue/head{?token}` [Queue
head](#/reference/request-queues/queue-head)

For example, to download data from a dataset of the actor run in XML format,
For example, to download data from a dataset of the Actor run in XML format,
send HTTP GET request to the following URL:

```
Expand All @@ -64,12 +64,12 @@ get:

In order to save new items to the dataset, send HTTP POST request with JSON
payload to the same URL.Gets an object that contains all the details about a
specific run of an actor.
specific run of an Actor.

By passing the optional `waitForFinish` parameter the API endpoint will
synchronously wait for the run to finish.

This is useful to avoid periodic polling when waiting for actor run to
This is useful to avoid periodic polling when waiting for Actor run to
complete.

This endpoint does not require the authentication token. Instead, calls are authenticated using a hard-to-guess ID of the run. However,
Expand Down Expand Up @@ -218,8 +218,8 @@ put:
summary: Update status message
description: |
You can set a single status message on your run that will be displayed in
the Apify Console UI. During an actor run, you will typically do this in order
to inform users of your actor about the actor's progress.
the Apify Console UI. During an Actor run, you will typically do this in order
to inform users of your Actor about the Actor's progress.

The request body must contain `runId` and `statusMessage` properties. The
`isStatusMessageTerminal` property is optional and it indicates if the
Expand Down
4 changes: 2 additions & 2 deletions apify-api/openapi/paths/actor-runs/actor-runs@{runId}@abort.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ post:
- Actor runs/Abort run
summary: Abort run
description: |
Aborts an actor run and returns an object that contains all the details
Aborts an Actor run and returns an object that contains all the details
about the run.

Only runs that are starting or running are aborted. For runs with status
Expand All @@ -21,7 +21,7 @@ post:
- name: gracefully
in: query
description: |-
If true passed, the actor run will abort gracefully.
If true passed, the Actor run will abort gracefully.
It will send `aborting` and `persistState` event into run and force-stop the run after 30 seconds.
It is helpful in cases where you plan to resurrect the run later.
style: form
Expand Down
18 changes: 9 additions & 9 deletions apify-api/openapi/paths/actor-runs/actor-runs@{runId}@metamorph.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,16 @@ post:
- Actor runs/Metamorph run
summary: Metamorph run
description: |
Transforms an actor run into a run of another actor with a new input.
Transforms an Actor run into a run of another Actor with a new input.

This is useful if you want to use another actor to finish the work
of your current actor run, without the need to create a completely new run
This is useful if you want to use another Actor to finish the work
of your current Actor run, without the need to create a completely new run
and waiting for its finish.

For the users of your actors, the metamorph operation is transparent, they
will just see your actor got the work done.
For the users of your Actors, the metamorph operation is transparent, they
will just see your Actor got the work done.

Internally, the system stops the Docker container corresponding to the actor
Internally, the system stops the Docker container corresponding to the Actor
run and starts a new container using a different Docker image.

All the default storages are preserved and the new input is stored under the
Expand All @@ -32,7 +32,7 @@ post:
example: 3KH8gEpp4d8uQSe8T
- name: targetActorId
in: query
description: ID of a target actor that the run should be transformed into.
description: ID of a target Actor that the run should be transformed into.
required: true
style: form
explode: true
Expand All @@ -42,11 +42,11 @@ post:
- name: build
in: query
description: |
Optional build of the target actor.
Optional build of the target Actor.

It can be either a build tag or build number. By default, the run uses
the build specified in the default run configuration for the target
actor (typically `latest`).
Actor (typically `latest`).
style: form
explode: true
schema:
Expand Down
2 changes: 1 addition & 1 deletion apify-api/openapi/paths/actor-runs/actor-runs@{runId}@reboot.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ post:
- Actor runs/Reboot run
summary: Reboot run
description: |
Reboots an actor run and returns an object that contains all the details
Reboots an Actor run and returns an object that contains all the details
about the rebooted run.

Only runs that are running, i.e. runs with status `RUNNING` can be rebooted.
Expand Down
4 changes: 2 additions & 2 deletions apify-api/openapi/paths/actor-runs/actor-runs@{runId}@resurrect.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ post:
- Actor runs/Resurrect run
summary: Resurrect run
description: |
Resurrects a finished actor run and returns an object that contains all the details about the resurrected run.
Resurrects a finished Actor run and returns an object that contains all the details about the resurrected run.
Only finished runs, i.e. runs with status `FINISHED`, `FAILED`, `ABORTED` and `TIMED-OUT` can be resurrected.
Run status will be updated to RUNNING and its container will be restarted with the same storages
(the same behaviour as when the run gets migrated to the new server).
Expand All @@ -25,7 +25,7 @@ post:
schema:
type: string
example: 0.1.234
description: Specifies the actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the run that is being resurrected (typically `latest`).
description: Specifies the Actor build to run. It can be either a build tag or build number. By default, the run uses the build specified in the run that is being resurrected (typically `latest`).
- name: timeout
in: query
required: false
Expand Down
24 changes: 12 additions & 12 deletions ...y-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync-get-dataset-items.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,17 @@ post:
- Actor tasks/Run task synchronously and get dataset items
summary: Run task synchronously and get dataset items (POST)
description: |
Runs an actor task and synchronously returns its dataset items.
Runs an Actor task and synchronously returns its dataset items.

The run must finish in 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> seconds
otherwise the HTTP request fails with a timeout error (this won't abort
the run itself).

Optionally, you can override the actor input configuration by passing a JSON
Optionally, you can override the Actor input configuration by passing a JSON
object as the POST payload and setting the `Content-Type: application/json` HTTP header.

Note that if the object in the POST payload does not define a particular
input property, the actor run uses the default value defined by the task (or the actor's
input property, the Actor run uses the default value defined by the task (or the Actor's
input schema if not defined by the task).

You can send all the same options in parameters as the [Get Dataset
Expand All @@ -26,7 +26,7 @@ post:
If the connection breaks, you will not receive any information about the run
and its status.

Input fields from actor task configuration can be overloaded with values
Input fields from Actor task configuration can be overloaded with values
passed as the POST payload.

Just make sure to specify the `Content-Type` header as `application/json`
Expand Down Expand Up @@ -73,7 +73,7 @@ post:
The maximum number of items that the task run should return. This is
useful for pay-per-result tasks, as it allows you to limit the number of
results that will be charged to your subscription. You can access the
maximum number of items in your actor by using the
maximum number of items in your Actor by using the
`ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
style: form
explode: true
Expand All @@ -84,7 +84,7 @@ post:
- name: build
in: query
description: |
Specifies the actor build to run. It can be either a build tag or build
Specifies the Actor build to run. It can be either a build tag or build
number. By default, the run uses the build specified in the task
settings (typically `latest`).
style: form
Expand All @@ -95,10 +95,10 @@ post:
- name: webhooks
in: query
description: |
Specifies optional webhooks associated with the actor run, which can be
Specifies optional webhooks associated with the Actor run, which can be
used to receive a notification

e.g. when the actor finished or failed. The value is a Base64-encoded
e.g. when the Actor finished or failed. The value is a Base64-encoded
JSON array of objects defining the webhooks. For more information, see

[Webhooks
Expand Down Expand Up @@ -462,7 +462,7 @@ get:
The maximum number of items that the task run should return. This is
useful for pay-per-result tasks, as it allows you to limit the number of
results that will be charged to your subscription. You can access the
maximum number of items in your actor by using the
maximum number of items in your Actor by using the
`ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
style: form
explode: true
Expand All @@ -473,7 +473,7 @@ get:
- name: build
in: query
description: |
Specifies the actor build to run. It can be either a build tag or build
Specifies the Actor build to run. It can be either a build tag or build
number. By default, the run uses the build specified in the task
settings (typically `latest`).
style: form
Expand All @@ -484,10 +484,10 @@ get:
- name: webhooks
in: query
description: |
Specifies optional webhooks associated with the actor run, which can be
Specifies optional webhooks associated with the Actor run, which can be
used to receive a notification

e.g. when the actor finished or failed. The value is a Base64-encoded
e.g. when the Actor finished or failed. The value is a Base64-encoded
JSON array of objects defining the webhooks. For more information, see

[Webhooks
Expand Down
24 changes: 12 additions & 12 deletions apify-api/openapi/paths/actor-tasks/actor-tasks@{actorTaskId}@run-sync.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,17 @@ post:
- Actor tasks/Run task synchronously
summary: Run task synchronously (POST)
description: |
Runs an actor task and synchronously returns its output.
Runs an Actor task and synchronously returns its output.

The run must finish in 300<!-- MAX_ACTOR_JOB_SYNC_WAIT_SECS --> seconds
otherwise the HTTP request fails with a timeout error (this won't abort
the run itself).

Optionally, you can override the actor input configuration by passing a JSON
Optionally, you can override the Actor input configuration by passing a JSON
object as the POST payload and setting the `Content-Type: application/json` HTTP header.

Note that if the object in the POST payload does not define a particular
input property, the actor run uses the default value defined by the task (or actor's input
input property, the Actor run uses the default value defined by the task (or Actor's input
schema if not defined by the task).

Beware that it might be impossible to maintain an idle HTTP connection for
Expand All @@ -23,7 +23,7 @@ post:
If the connection breaks, you will not receive any information about the run
and its status.

Input fields from actor task configuration can be overloaded with values
Input fields from Actor task configuration can be overloaded with values
passed as the POST payload.

Just make sure to specify `Content-Type` header to be `application/json` and
Expand Down Expand Up @@ -70,7 +70,7 @@ post:
The maximum number of items that the task run should return. This is
useful for pay-per-result tasks, as it allows you to limit the number of
results that will be charged to your subscription. You can access the
maximum number of items in your actor by using the
maximum number of items in your Actor by using the
`ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
style: form
explode: true
Expand All @@ -81,7 +81,7 @@ post:
- name: build
in: query
description: |
Specifies the actor build to run. It can be either a build tag or build
Specifies the Actor build to run. It can be either a build tag or build
number. By default, the run uses the build specified in the task
settings (typically `latest`).
style: form
Expand All @@ -102,10 +102,10 @@ post:
- name: webhooks
in: query
description: |
Specifies optional webhooks associated with the actor run, which can be
Specifies optional webhooks associated with the Actor run, which can be
used to receive a notification

e.g. when the actor finished or failed. The value is a Base64-encoded
e.g. when the Actor finished or failed. The value is a Base64-encoded
JSON array of objects defining the webhooks. For more information, see

[Webhooks
Expand Down Expand Up @@ -205,7 +205,7 @@ get:
The maximum number of items that the task run should return. This is
useful for pay-per-result tasks, as it allows you to limit the number of
results that will be charged to your subscription. You can access the
maximum number of items in your actor by using the
maximum number of items in your Actor by using the
`ACTOR_MAX_PAID_DATASET_ITEMS` environment variable.
style: form
explode: true
Expand All @@ -216,7 +216,7 @@ get:
- name: build
in: query
description: |
Specifies the actor build to run. It can be either a build tag or build
Specifies the Actor build to run. It can be either a build tag or build
number. By default, the run uses the build specified in the task
settings (typically `latest`).
style: form
Expand All @@ -237,10 +237,10 @@ get:
- name: webhooks
in: query
description: |
Specifies optional webhooks associated with the actor run, which can be
Specifies optional webhooks associated with the Actor run, which can be
used to receive a notification

e.g. when the actor finished or failed. The value is a Base64-encoded
e.g. when the Actor finished or failed. The value is a Base64-encoded
JSON array of objects defining the webhooks. For more information, see

[Webhooks
Expand Down
Loading
Loading