feat: Rename legacy act-* API operationIds to actor-* for consistency#2646
feat: Rename legacy act-* API operationIds to actor-* for consistency#2646jancurn wants to merge 2 commits into
Conversation
Rename the legacy `act_*`/`acts_*` operationIds in the OpenAPI source to `actor_*`/`actors_*` so the generated doc page slugs become `/api/v2/actor-*`, matching the canonical `/v2/actors/` naming. operationId only drives doc-slug generation and client method hints; the live API at api.apify.com/v2 is unchanged (paths, methods, parameters, and request/response schemas untouched). - 63 operations renamed; matching `code_samples/*` files renamed to keep their samples attached. - 7 deprecated actor-scoped build/run duplicates (act-build-get, act-builds-get, act-build-abort-post, act-run-get, act-runs-get, act-run-abort-post, act-run-metamorph-post) keep their operationIds; their legacy URLs 301-redirect to the canonical standalone actor-build*/actor-run* pages. - nginx: add 301 redirects `/api/v2/act-*` -> `/api/v2/actor-*` and `/api/v2/acts-*` -> `/api/v2/actors-*` covering every old slug. - Update internal doc links and the llms.txt index exclusion patterns. https://claude.ai/code/session_01Q4HrVBuRKYG46ztwLXQkHz
jancurn
requested review from
fnesveda,
honzajavorek,
janbuchar,
marcel-rbro and
szaganek
as code owners
|
✅ Preview for this PR (commit |
jancurn
changed the title
|
Sorry guys for this "drop". It's a lot of changes but should be fairly safe I think. |
| # Actor API reference operation pages: legacy `act-*`/`acts-*` slugs -> `actor-*`/`actors-*`. | ||
| # Each page slug is kebab-case(operationId); the `act_*`/`acts_*` operationIds were renamed to | ||
| # `actor_*`/`actors_*` to match the canonical `/v2/actors/` naming. The deprecated actor-scoped | ||
| # build/run duplicates (act-build-get, act-builds-get, act-build-abort-post, act-run-get, | ||
| # act-runs-get, act-run-abort-post, act-run-metamorph-post) resolve to their canonical | ||
| # standalone actor-build*/actor-run* pages via the same act- -> actor- rewrite. | ||
| rewrite ^/api/v2/acts-(.*)$ /api/v2/actors-$1 permanent; | ||
| rewrite ^/api/v2/act-(.*)$ /api/v2/actor-$1 permanent; | ||
|
|
There was a problem hiding this comment.
Just off the top of my head I think this is problematic, weird UX, and partly a bug.
The genuinely deprecated endpoints (act-build-get, act-run-get, abort, metamorph) are already marked deprecated: true in the spec, with an admonition that tells you they're deprecated and links to the canonical one. A silent 301 strips that context. You click the endpoint and inexplicably land on a different page with no explanation.
But act-builds-get and act-runs-get aren't deprecated at all. They're the Actor-scoped list endpoints (GET /v2/acts/{actorId}/builds, GET /v2/acts/{actorId}/runs). The broad rule at line 800 catches them and redirects to actor-builds-get / actor-runs-get, which are the account-wide "Get user builds/runs list" endpoints.
Different scope, no equivalent in the new namespace. So that's a straight regression: those pages serve correct content on prod today and would 301 away after this.
…irect The act-(.*) catch-all also matched 7 Actor-scoped build/run pages that were intentionally not renamed and still exist: it stripped the deprecation notice from the 5 deprecated pages (silent 301) and, worse, 301'd the two non-deprecated Actor-scoped list pages (act-builds-get, act-runs-get) to the account-wide actor-builds-get/actor-runs-get, which have a different scope and no equivalent. Add an exact-match guard that serves those 7 via `break`; every other moved act-* slug (incl. prefix-sharing ones like act-build-default-get) still 301s. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q4HrVBuRKYG46ztwLXQkHz
4 participants
Standardizes API operation IDs across the OpenAPI specification by renaming all
act_*andacts_*operationIds toactor_*andactors_*respectively, aligning with the canonical/v2/actors/endpoint naming convention.The main effect is that we fix the URLs in API docs from e.g. https://docs.apify.com/api/v2/acts-post to https://docs.apify.com/api/v2/actors-post
Key changes:
actor_prefix instead ofact_(e.g.,act_get→actor_get,acts_get→actors_get)act-*andacts-*URL slugs to theiractor-*andactors-*equivalents with 301 permanent redirectsact_get.sh→actor_get.sh)The changes maintain backward compatibility through nginx redirects while establishing consistent naming across the API reference documentation.
https://claude.ai/code/session_01Q4HrVBuRKYG46ztwLXQkHz