Construir APIs REST listas para producción: una lista práctica

Diseñar para quienes la van a llamar

Las buenas APIs son predecibles. Use sustantivos para los recursos, métodos y códigos HTTP estándar, nombres coherentes y un único formato de error. Un desarrollador que entiende un endpoint debería poder adivinar cómo funciona el siguiente.

• Nombres y plurales de recursos coherentes.
• Paginación, filtrado y ordenación en cada endpoint de listado.
• Un cuerpo de error estándar con código, mensaje y detalles.
• Claves de idempotencia para las operaciones que crean pagos o pedidos.

Seguridad en cada petición

Autentique cada llamada, normalmente con OAuth 2.0 o tokens firmados, y autorice cada acción según el rol y el ámbito de quien llama. Valide las entradas en la frontera, limite el tamaño de las peticiones y el ritmo de los clientes para que una integración no pueda agotar el servicio.

Versionar sin romper a los consumidores

Los cambios aditivos (campos nuevos, endpoints nuevos) no deberían romper a nadie. Eliminar o renombrar campos, sí. Versione la API de forma explícita, anuncie las retiradas con antelación y mantenga las versiones antiguas hasta que los consumidores hayan migrado.

Documentación y experiencia de desarrollo

Una especificación OpenAPI generada a partir del código mantiene la documentación exacta. Añada ejemplos de peticiones y respuestas, instrucciones de autenticación y un entorno sandbox para que los integradores puedan probar con seguridad.

Operarla como un producto

Las APIs que perduran son aquellas cuyos responsables saben cómo se usan, y detectan pronto cuando algo va mal.

• Seguir la latencia y la tasa de errores por endpoint y por cliente.
• Registrar identificadores de petición para rastrear problemas de extremo a extremo.
• Usar webhooks con reintentos y firmas para las notificaciones de eventos.
• Publicar información de estado y un registro de cambios para los consumidores.