Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

docs(standby): call out endpoint discoverability as a first-class Standby requirement

Aperta Adatta ai principianti
  • Qualcosa non va?
#2,742 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
68/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Tranquilla
Stack tecnologico
javascript
Ambito
documentation

Direzione di ricerca

Inizia dalla pagina della documentazione di Standby in platform/actors/development/programming-interface/standby e verifica come spiega il routing degli endpoint e webServerSchema in actor.json. Aggiungi una sottosezione «Individuabilità degli endpoint» che tratti i tre pattern suggeriti e identifichi come anti-pattern il testo esplicativo sul percorso root. Il lavoro è completato quando la pagina comunica queste raccomandazioni e rimanda allo schema.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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:

  1. Bind the primary handler on / — simplest; the URL you hand out IS the URL clients hit.
  2. Serve an OpenAPI spec at /openapi.json — clients can auto-discover the shape. Cross-reference the webServerSchema in actor.json.
  3. 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 the ts-standby template AGENTS.md.
  • Platform-side (apify/actor-standby-controller #340): auto-serve webServerSchema at /openapi.json on 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.

Lingua principale
JavaScript
Stelle
82
Fork
240
Merge medio
4g 2h
PR unite (30g)
44

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di apify/apify-docs

Tutte le issue di apify/apify-docs

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.