APIs: el contrato entre dos programas

En la lección anterior dividiste un sistema en un cliente que pregunta y un servidor que responde. En el momento en que haces eso, aparece una nueva pregunta: ¿qué envía exactamente el cliente y qué vuelve exactamente? Tú y el cliente son ahora dos programas separados que se actualizarán en días distintos, quizá por personas distintas, quizá en años distintos. Algo tiene que quedarse fijo entre los dos. Ese algo es la API.

Una API (interfaz de programación de aplicaciones) es un contrato, y vale la pena leer esa palabra al pie de la letra. Dice: si envías esta petición, recibirás esta respuesta. No "más o menos esto", no "normalmente esto". Una petición se arma con cuatro cosas: un método, que dice qué tipo de acción es (GET lee y no cambia nada, POST crea, DELETE borra); una ruta, que dice de qué cosa estás hablando (/orders/77); encabezados, que llevan metadatos como el tipo de contenido o un token; y a veces un cuerpo con datos. La respuesta tiene un código de estado y, casi siempre, un cuerpo con JSON.

GET    /v1/orders/77      -> 200 OK, one order
POST   /v1/orders         -> 201 Created, the new order
DELETE /v1/orders/77      -> 204 No Content, nothing left
GET    /v1/orders/999     -> 404 Not Found, no such order
POST   /v1/orders/broken  -> 400 Bad Request, the body is wrong
GET    /v1/admin/users    -> 401 Unauthorized, no token sent

Los códigos de estado son el lenguaje común para los resultados, y solo necesitas unas pocas familias. 2xx significa que funcionó. 4xx significa que la petición estaba mal: 404 para algo que no existe, 400 para un cuerpo que no tiene sentido, 401 para un token ausente o inválido. 5xx significa que el servidor se rompió mientras manejaba una petición que por lo demás era válida. Esta división no es burocracia; le dice al cliente qué hacer después. Un 404 es definitivo: no reintentes. Un 500 puede ser temporal: reintentar es razonable. Sin la división, cada cliente tiene que adivinar, y cada cliente adivina distinto.

Algún día la forma de una respuesta tiene que cambiar. Quizá total era el número 12.90 y ahora el negocio necesita una moneda junto a él, así que total pasa a ser un objeto. Tu propia página se puede actualizar esa misma tarde; la app del teléfono no, porque la gente mantiene versiones viejas instaladas durante meses, y el script de un socio puede que lo actualice alguien que nunca oyó hablar de ti. Este es el momento de decidir si el cambio es rompiente. Si todo cliente existente que no cambie su código va a fallar ahora, es rompiente, y necesita una nueva versión: /v2/orders/77 junto al viejo /v1/orders/77, y ambas activas hasta que la vieja se retire por fin.