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

Abierto Apto para principiantes
  • ¿Algo no está bien?
#2,742 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
68/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Tranquilo
Stack tecnológico
javascript
Área
documentation

Línea de trabajo

Empieza por la página de documentación de Standby en platform/actors/development/programming-interface/standby y comprueba cómo explica el enrutamiento de endpoints y webServerSchema en actor.json. Añade un subapartado «Descubribilidad de endpoints» que cubra los tres patrones sugeridos e identifique la prosa sobre la ruta raíz como un anti-pattern. El trabajo estará hecho cuando la página comunique estas recomendaciones y haga referencia al esquema.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
JavaScript
Estrellas
82
Forks
240
Merge medio
4 d 13 h
PR fusionados (30 d)
57

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de apify/apify-docs

Todos los issues de apify/apify-docs

Issues similares

Más issues de JavaScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.