Cómo redactar un resumen de API que los desarrolladores puedan usar
Beta privada. El acceso es por lista de espera y los planes de pago se abren cuando termine la beta. Apúntate a la lista de espera.
Un resumen de API es la primera página que lee un desarrollador y, a menudo, la única antes de decidir si integra la API. Debe responder a unas pocas preguntas con rapidez y estar siempre en el mismo sitio, con los mismos encabezados.
Qué incluir, en orden
- Resumen. Qué hace la API, a quién va dirigida y un uso típico, en dos o tres frases.
- URL base. Una línea con la versión en la ruta, más la URL del entorno de pruebas si existe.
- Autenticación. Cómo obtener una clave, en qué cabecera se envía y si las claves cambian según el entorno.
- Endpoints. Una tabla con el método, la ruta, una descripción de una línea y si cada endpoint está paginado y si es idempotente. Los detalles completos de los parámetros pueden estar en la referencia.
- Límites de uso. El límite expresado como número, las cabeceras que lo informan y qué debe hacer un cliente cuando se supera.
- Versionado. Qué se considera un cambio incompatible y cuántos días de aviso recibe una versión retirada.
- Errores. Una tabla con los códigos de estado, los códigos de error, su significado y si cada uno se puede reintentar sin riesgo.
Errores que hacen perder tiempo a los desarrolladores
- Poner la autenticación en una página aparte, de modo que la primera llamada queda bloqueada por un enlace que el lector tiene que encontrar.
- Listar endpoints sin indicar cuáles de ellos están paginados ni qué escrituras son idempotentes, de modo que un reintento puede crear un registro duplicado.
- Documentar solo el camino de éxito, sin tabla de errores, de modo que cada cliente inventa su propio tratamiento.
- Indicar los límites de uso como "razonables" o "uso justo" en lugar de un número y el nombre de una cabecera.
- No decir nada sobre la obsolescencia, de modo que una versión retirada deja de funcionar sin aviso.
- Dejar que el formato varíe de una API a otra, de modo que los desarrolladores tienen que volver a aprender la página cada vez que abren una nueva.
Ejemplo práctico: Parcel Tracking API
Este es un ejemplo ficticio. La Parcel Tracking API, sus claves, identificadores, límites y códigos de error son inventados, pero coinciden entre sí, de modo que cada sección se puede comprobar contra las demás.
Resumen. La Parcel Tracking API permite a un comerciante crear un envío, consultar su estado actual y listar los eventos de seguimiento de cada paquete. Está pensada para desarrolladores que conectan una tienda en línea o un sistema de almacén con las etiquetas de envío y las actualizaciones de entrega.
URL base. https://api.parceltrack.example/v2 para producción. El entorno de pruebas es https://sandbox.parceltrack.example/v2 y solo acepta claves de prueba.
Autenticación. La clave de API se envía como token bearer en la cabecera Authorization: Authorization: Bearer pt_live_.... Las claves que empiezan por pt_live_ solo funcionan con la URL base de producción, y las que empiezan por pt_test_ solo funcionan en el entorno de pruebas. Las claves se crean en Ajustes y después en Claves de API. Una clave revocada devuelve 401 en su siguiente petición.
Endpoints. Todas las rutas siguientes son relativas a la URL base.
| Método | Ruta | Descripción | Paginado | Idempotente |
|---|---|---|---|---|
| POST | /shipments | Crea un envío y recibe su número de seguimiento. | no | solo con la cabecera Idempotency-Key |
| GET | /shipments/{id} | Consulta un envío y su estado actual. | no | sí |
| GET | /shipments | Lista los envíos de la cuenta, del más reciente al más antiguo. | sí | sí |
| GET | /shipments/{id}/events | Lista los eventos de seguimiento de un envío, del más reciente al más antiguo. | sí | sí |
| POST | /shipments/{id}/cancel | Cancela un envío que todavía no ha sido recogido. | no | no |
POST /shipments es idempotente solo cuando se envía la cabecera Idempotency-Key. La API conserva esa clave durante 24 horas, y un reintento con la misma clave devuelve el envío original en lugar de crear un segundo. Los endpoints paginados aceptan limit (de 1 a 100, por defecto 25) y cursor, y devuelven next_cursor, que es null en la última página. Cancelar dos veces un envío devuelve 409, así que conviene comprobar el estado antes de reintentar una cancelación.
Límites de uso. Producción permite 300 peticiones por minuto y clave de API. El entorno de pruebas permite 60 peticiones por minuto y clave. Cada respuesta incluye tres cabeceras: RateLimit-Limit (el cupo de la ventana), RateLimit-Remaining (peticiones que quedan en la ventana actual) y RateLimit-Reset (segundos hasta que se reinicia la ventana). Las peticiones rechazadas cuentan para el límite.
Cuando una clave supera su cupo, la API devuelve 429 con una cabecera Retry-After que indica el número de segundos de espera. Hay que esperar al menos ese tiempo y después reintentar. Si las peticiones siguen devolviendo 429, conviene aplicar un retroceso exponencial que empiece en 1 segundo, duplique la espera en cada intento, añada una variación aleatoria y se detenga tras 5 intentos. No se debe reintentar en un bucle cerrado.
Versionado y obsolescencia. La versión actual es v2, y figura en la ruta de la URL base. Un cambio incompatible es aquel que puede hacer fallar a un cliente que funciona: eliminar o renombrar un campo, cambiar el tipo de un campo, cambiar el significado de un código de error o hacer obligatorio un parámetro opcional. Añadir endpoints, parámetros opcionales y campos de respuesta no es incompatible, por lo que los clientes deben ignorar los campos de respuesta que no reconozcan. Una versión obsoleta devuelve una cabecera Deprecation y una cabecera Sunset con la fecha de retirada. El aviso se da con al menos 180 días de antelación a la fecha de Sunset, y el titular de la cuenta recibe un correo electrónico cuando empieza el aviso.
Errores. Cada error devuelve un cuerpo JSON con un código error de la tabla siguiente y un message para los registros. Conviene interpretar el código, no el texto del mensaje.
| Estado | Código de error | Significado | Reintento seguro |
|---|---|---|---|
| 400 | invalid_request | Falta un campo o tiene un formato incorrecto. El cuerpo enumera cada problema en details. | no |
| 401 | unauthorized | La clave falta, está revocada o pertenece al otro entorno. | no |
| 404 | shipment_not_found | No existe ningún envío con ese ID en la cuenta. | no |
| 409 | shipment_state_conflict | La acción no encaja con el estado del envío, por ejemplo cancelar un envío que ya ha sido recogido. | no |
| 429 | rate_limited | La clave ha agotado su cupo del minuto actual. | sí, tras el retardo de Retry-After |
| 503 | service_unavailable | Interrupción temporal del servicio. Reintentar con retroceso y reutilizar la misma Idempotency-Key en las peticiones POST. | sí, con retroceso |
Frases débiles frente a frases sólidas
Tres frases típicas de resúmenes, cada una seguida de una versión más sólida del mismo punto.
Débil: "La autenticación usa tokens."
Sólida: "La clave de API se envía en la cabecera Authorization, precedida de Bearer. Las claves que empiezan por pt_test_ solo funcionan en el entorno de pruebas, y las que empiezan por pt_live_ solo funcionan en producción."
Débil: "Los límites de uso se aplican a todos los endpoints."
Sólida: "Cada clave puede enviar 300 peticiones por minuto a producción y 60 al entorno de pruebas. Se lee RateLimit-Remaining en cada respuesta. Ante un 429, se espera el número de segundos indicado en Retry-After antes de la siguiente petición."
Débil: "Las listas están paginadas."
Sólida: "Los endpoints de listado devuelven 25 elementos por defecto y hasta 100 si se pasa limit. Para obtener la página siguiente, se pasa el valor de next_cursor de cada respuesta como cursor. Cuando next_cursor es null, se ha llegado a la última página."
Lista de comprobación de revisión
Quien revisa puede repasar estas ocho preguntas en unos cinco minutos.
- ¿Puede un desarrollador hacer una primera llamada correcta usando solo esta página?
- ¿La URL base incluye la versión y hay una URL de entorno de pruebas?
- ¿La sección de autenticación indica la cabecera, el formato de la clave y el entorno en el que funciona cada clave?
- ¿Cada endpoint indica si está paginado y si es idempotente?
- ¿Los límites de uso se dan como números, con los nombres de las cabeceras y el comportamiento ante el 429?
- ¿La sección de versionado define qué es un cambio incompatible e indica el plazo de aviso antes de la retirada?
- ¿Cada fila de error indica si el reintento es seguro, y esa respuesta coincide con la tabla de endpoints?
- ¿Los números, los identificadores y los códigos coinciden en todas las secciones?
Cómo mantener coherentes los resúmenes
Si se mantienen varias API, o se escriben para varios clientes, una plantilla fija mantiene el mismo orden y las mismas tablas. Wordspecs tiene una plantilla de resumen de API con estos campos, y el resumen de API de ejemplo (un servicio ficticio de seguimiento de paquetes) muestra su aspecto. Las hojas se exportan a Markdown, PDF y Word.
Relacionado: exportar a Markdown, PDF y Word.