docs(standby): call out endpoint discoverability as a first-class Standby requirement
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 2/5
- 見積もり時間
- 1〜3時間
- 初心者へのやさしさ
- 68/100
- issue の種類
- ドキュメント
- 明瞭さ
- 明確に書かれている
- 活発さ
- 静か
- 技術スタック
- javascript
調査の方向性
platform/actors/development/programming-interface/standby にある Standby のドキュメントページから始め、endpoint routing と actor.json 内の webServerSchema をどのように説明しているか確認してください。提案されている3つのパターンを扱い、root path に関する文章をアンチパターンとして示す「Endpoint discoverability」サブセクションを追加してください。このページでこれらの推奨事項が伝わり、スキーマを相互参照していれば完了です。
索引モデルが issue の本文から書いたものです。
説明
Problem
The Apify Standby documentation (platform/actors/development/programming-interface/standby) describes how to build a Standby Actor but does not call out endpoint discoverability as a first-class concern.
Agents (and human authors) commonly land on a topology where:
- Primary HTTP handler is bound on
/metadata(or/api, or another verb-shaped path). - Root
/returns plain-text help:"Actor is ready. Use GET /metadata?url=<url>".
The Actor is reachable, but only by a human reading the help text — programmatic clients hitting / get non-JSON prose and have no machine-readable way to find the real endpoint.
Observed in an eval run (scenario 06, agent's Actor davehan/metadata-api) — deployed Actor was fully functional at /metadata?url=… but invisible to any programmatic client.
Suggested change
Add a "Endpoint discoverability" subsection to the Standby documentation calling out that a well-formed Standby Actor should adopt one of three patterns:
- Bind the primary handler on
/— simplest; the URL you hand out IS the URL clients hit. - Serve an OpenAPI spec at
/openapi.json— clients can auto-discover the shape. Cross-reference thewebServerSchemainactor.json. - Return a machine-readable
{"endpoints": [...]}JSON at/— minimal escape hatch when/is reserved for something else.
Root-path prose (Actor is ready. Use GET /metadata?...) should be explicitly called out as an anti-pattern.
Related
- Sibling change in
apify/agent-skills— the same teaching in the public skill. - Sibling change in
apify/actor-templates— teaching baked into thets-standbytemplate AGENTS.md. - Platform-side (
apify/actor-standby-controller#340): auto-servewebServerSchemaat/openapi.jsonon the Standby URL. That closes the platform-side loop; docs closes the human-authoring loop.
Impact
Medium. Docs are the primary teaching surface — agents that pre-train on Apify docs and human authors both benefit.
Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.
- 主要言語
- JavaScript
- スター
- 82
- フォーク
- 240
- 平均マージ
- 4日 3時間
- マージ済み PR（30日）
- 40
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
apify/apify-docs のほかの issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 85/100
apify/apify-docs#3071 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 85/100
apify/apify-docs#3049 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1〜3時間 初心者へのやさしさ 82/100
apify/apify-docs#2741 ·
メンテナーはふだん 1 日以内に返信
-
low priority t-unblocking tech enhancement
難易度 2/5 1〜3時間 初心者へのやさしさ 65/100
apify/apify-docs#2451 ·
メンテナーはふだん 1 日以内に返信
-
t-builders t-docs
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
apify/apify-docs#1703 ·
メンテナーはふだん 1 日以内に返信
apify/apify-docs の issue をすべて見る
似ている issue
-
[Website] Catalog: unknown sort value and mixed-case technology in the URL break the filters対応中かも @barbierajput378-pixel が今日担当しました。 オープンarea/website framework/jekyll help wanted language/css language/javascript language/markdown
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100
meshery/meshery.io#3088 · コメント 1 件 ·
メンテナーはふだん 2 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
firecrawl/firecrawl-mcp-server#548 ·
メンテナーはふだん 1 日以内に返信
-
Area:WebGL p5.js 2.0+
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
processing/p5.js#9302 ·
メンテナーはふだん 3 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
メンテナーはふだん 1 日以内に返信
-
documentation good first issue hacktoberfest
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
wassim-azi/agy-powerline#47 ·
メンテナーはふだん 1 日以内に返信