Válido es solo el principio
Un ejemplo obtenido de un schema puede ser sintácticamente correcto y no enseñar nada. string, 123 y foo satisfacen validadores, pero ocultan el dominio. Un buen ejemplo explica por qué existe la petición y qué permite hacer el resultado.
Usa valores realistas sin incluir secretos ni datos personales reales.
Construye una pequeña historia
Prefiere una secuencia parecida a una tarea real: crear un recurso, recuperarlo, actualizarlo y manejar un fallo o limpieza. Reutiliza identificadores para que se vean las relaciones.
En páginas de referencia independientes, enlaza al workflow pertinente en lugar de duplicar un tutorial completo.
Enseña la respuesta importante
No te detengas en el request. Incluye status, headers relevantes y body. Explica campos poco obvios. Si la operación es asíncrona, muestra cómo sabe el cliente que terminó.
Los errores merecen el mismo cuidado: un validation error realista puede enseñar más que otro happy path.
Haz los ejemplos ejecutables
Cuando sea posible, ejecuta requests en CI o valida payloads contra el contrato. Guarda samples como archivos o fragmentos generados, no copies manualmente el mismo código por varias páginas.
Optimiza para la adaptación
Explica qué valores debe cambiar el lector y qué supuestos deben mantenerse. El objetivo es transferir un modelo mental.
Si el ejemplo no facilita diseñar la siguiente petición, probablemente es decoración.
Ejemplo aplicado
Convierte «Los ejemplos de API deben enseñar un flujo, no decorar la referencia» en una tarea completa de desarrollador. Usa un recurso ficticio pero realista, como un informe, dispositivo o pedido, y describe el camino más corto desde la autenticación hasta un resultado correcto. Incluye la petición, los campos importantes de la respuesta, un fallo probable y la siguiente acción después de ese fallo.
Revisa el ejemplo como si fueras a construir un cliente con él:
- qué valores debe sustituir el desarrollador;
- qué identificadores devuelve el servidor y se reutilizan después;
- qué estado o campo confirma el éxito;
- qué debe hacer el cliente ante credenciales, datos o límites incorrectos.
La documentación de API es útil cuando permite predecir la interacción con el sistema, no solo reconocer nombres de endpoints.
Lista rápida de revisión editorial
- Válido es solo el principio. Un ejemplo obtenido de un schema puede ser sintácticamente correcto y no enseñar nada.
- Construye una pequeña historia. Prefiere una secuencia parecida a una tarea real: crear un recurso, recuperarlo, actualizarlo y manejar un fallo o limpieza.
- Enseña la respuesta importante. No te detengas en el request.
- Haz los ejemplos ejecutables. Cuando sea posible, ejecuta requests en CI o valida payloads contra el contrato.
