Desarrollo de API con Laravel

Una API es una promesa hecha a alguien que no está en la sala. Ahí está toda la diferencia entre construir una API y construir el resto de una aplicación: sus propias pantallas pueden cambiar a la vez que el código que hay detrás, y un consumidor no.

La mayoría de las APIs Laravel que nos piden arreglar se construyeron como si eso no fuera cierto.

El contrato se genera, no se describe

Una especificación escrita a mano en un wiki queda desactualizada en dos sprints, y la primera persona en descubrirlo es un consumidor que ya construyó contra ella.

Así que el contrato sale del código: recursos tipados, validación de peticiones de la que se deriva la especificación, y un documento OpenAPI generado y publicado como parte de la compilación. Un cambio en la forma de una respuesta cambia el documento en el mismo pull request. Solo puede estar mal si el código está mal.

Los recursos son explícitos, no un modelo entregado a toJson(). Devolver un modelo directamente significa que una columna añadida por un motivo interno pasa a formar parte del contrato público el día en que se añade - y quitarla después es un cambio incompatible que usted nunca quiso hacer.

Versiones, decididas antes de necesitarlas

La versión uno es gratis y la dos no, así que la decisión que conviene tomar pronto es dónde vive la versión y qué cuenta como ruptura.

Añadir un campo no rompe nada. Quitarlo, renombrarlo, cambiarle el tipo o endurecer la validación, sí. La forma de la paginación, la forma de los errores y el formato de las fechas son parte del contrato aunque nadie los escriba como tales - y cada uno de los tres ha roto a un consumidor al menos una vez en nuestra experiencia.

Lo que dejamos montado es una política: los cambios aditivos salen de forma continua, los incompatibles reciben una versión nueva, ambas versiones conviven durante una ventana acordada, y a los consumidores se les avisa en lugar de que se enteren.

Autenticación con un solo dueño

Sanctum para clientes propios, Passport donde OAuth2 haga falta de verdad, y en ambos casos un único sitio que decide qué puede hacer un token.

El fallo que encontramos es la duplicación: un permiso comprobado en una policy para las rutas web y vuelto a implementar en un middleware para las rutas de la API, separándose poco a poco hasta que uno de los dos está equivocado. La autorización vive en policies a las que llaman ambas entradas, y las pruebas de la API afirman los casos negativos - no que la persona correcta pueda leer el registro, sino que la incorrecta no pueda.

Límite de peticiones por consumidor y no por IP, porque por IP se castiga a una oficina y se deja pasar un script. Habilidades acotadas a aquello para lo que existe el token, de modo que un token móvil filtrado no sea un token de administrador.

Lo que se rompe con datos reales

Paginación. La paginación por desplazamiento va bien hasta la página cuatrocientos, momento en el que la base de datos lee y descarta cuatrocientas páginas para darle una. Paginación por cursor para todo lo que crezca, decidida en el diseño porque cambiarla después es un cambio incompatible.

Filtrado y ordenación. Cada filtro que un consumidor puede pasar es un plan de consulta que usted tiene que poder servir. Una lista de permitidos, con un índice detrás de cada entrada, o ha publicado un endpoint que cualquiera con un token puede volver arbitrariamente lento.

Inclusiones. Dejar que un consumidor pida relaciones anidadas es una buena función y un generador de N+1. Carga anticipada dirigida por las inclusiones pedidas, con un límite de profundidad, o la comodidad se convierte en una caída.

Errores. Una sola forma, documentada, con un código legible por máquina que no cambia cuando cambia el mensaje legible por personas. Un consumidor que analiza sus cadenas de error es un consumidor al que va a romper por mejorar sus textos.

Cómo transcurre un encargo

Empieza por los consumidores. Mándenos quién llama a esta API, qué hace con ella, y el endpoint que más tickets de soporte ha generado. Con eso suele bastar para dimensionarlo.

Lo que vuelve es un alcance escrito: la lista de endpoints, la decisión de autenticación, la política de versionado, y qué entra en la primera fase frente a lo que deliberadamente no entra. Lleva un precio y es el documento al que se refiere el contrato, de modo que lo que usted firma y lo que nosotros construimos son la misma cosa.

Después el trabajo, en su repositorio y su proceso de revisión. La especificación se genera y se publica desde la primera fase, así que sus consumidores la leen mientras la API todavía se está construyendo.

Qué recibe

La API, la especificación generada y publicada donde los consumidores puedan alcanzarla, una batería de pruebas que cubre los negativos de autorización y los límites de la paginación, el límite de peticiones configurado por consumidor, y una política de versiones escrita que dice qué va a cambiar y qué no sin avisar.

Cuando la API se añade a una aplicación existente, recibe además lo que ese trabajo suele sacar a la luz: una lista de reglas de negocio que vivían en los controladores, y dónde viven ahora para que las dos entradas coincidan.

Sanctum o Passport fija cómo se autentican los consumidores, y es mucho más fácil fijarlo que cambiarlo después. La pregunta más difícil que hay debajo es si Laravel es siquiera el runtime adecuado para esta API. Y si el trabajo de la API es sobre todo hablar con la de otro, integración encaja mejor.