Un endpoint al que nadie sabe cómo llamar no existe. Puedes tener el controlador más limpio del mundo, y si un consumidor tiene que leerlo para averiguar qué campos son obligatorios, has entregado una biblioteca con el código fuente como manual.
El Capítulo 14 trataba de las personas que trabajan en el código. Este capítulo trata de las que programan contra él desde fuera: los desarrolladores del otro lado de la API, que nunca verán una línea de tu PHP y no deberían tener que verla.
Lo que necesita un consumidor
Siéntate donde se sienta tu consumidor. Tiene una tarea, un plazo y un token que alguien le envió. Lo que necesita de ti, en el orden en que lo necesita:
- Una primera llamada que funcione. Una petición que pueda pegar en una terminal y ver funcionar.
- Cómo autenticarse. Dónde va el token, qué aspecto tiene uno caducado.
- Cada endpoint, con una petición real y una respuesta real.
- Cada error que pueda recibir, y qué hacer con cada uno.
- Los límites. Límites de peticiones, tamaños de página, cuánto vive una clave de idempotencia.
- Qué va a cambiar, y cuándo. La política de versiones y un registro de cambios con fechas.
La mayoría de la documentación de APIs cubre el tercer punto y se detiene. El primero es el que decide si la tarde de un consumidor va bien.
curl https://licenses.example.com/api/licenses \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
Tres líneas al comienzo de la página. Si funcionan, el consumidor se fía de todo lo que hay debajo. Si no, nada más de lo que escribiste se leerá.
Describe la API en un formato que lean las máquinas
La respuesta de la industria a «¿cómo describo una API HTTP?» es OpenAPI: un documento JSON o YAML que lista cada ruta, cada parámetro, cada respuesta y la forma de cada una.
Un fragmento, para un endpoint de esta API:
/licenses:
post:
security:
- bearer: []
requestBody:
content:
application/json:
schema:
required: [name, domain]
properties:
name: { type: string, maxLength: 100 }
domain: { type: string, maxLength: 100 }
responses:
'201': { description: The created license }
'422': { description: Validation failed }
Un documento así te da varias cosas a la vez: un sitio de referencia navegable, colecciones de peticiones para herramientas como Postman, bibliotecas cliente generadas y un archivo que otras herramientas pueden comparar de una versión a la siguiente. Ese último uso es el que más le importa a este capítulo.