REST API Design: 10 Principles for Clean APIs — txt1.ai

Tres años en mi papel como Arquitecto Principal de API en un unicornio fintech, vi cómo nuestra app móvil fallaba de manera espectacular durante una demostración de producto a los inversores. ¿El culpable? Un único endpoint de API que devolvía 47MB de JSON porque alguien pensó que "más datos siempre es mejor". Ese momento embarazoso—y el retraso de $2M en la financiación que causó—me enseñó que el diseño de API no solo trata de hacer que las cosas funcionen. Se trata de hacer que funcionen de manera elegante, predecible y sostenible a gran escala.

Soy Marcus Chen, y he pasado los últimos 12 años diseñando APIs que manejan desde 50 solicitudes por día hasta 50 millones. He visto a ingenieros brillantes crear APIs tan complicadas que incluso ellos no podían recordar cómo usarlas seis meses después. También he visto a desarrolladores junior crear interfaces tan intuitivas que la documentación se volvió casi innecesaria. ¿La diferencia? Un compromiso con principios fundamentales que trascienden marcos, lenguajes y tendencias arquitectónicas.

Hoy, comparto los 10 principios que han guiado cada API exitosa que he construido—principios forjados a través de incidentes en producción, comentarios de usuarios y innumerables revisiones de código. Estos no son ideales teóricos; son pautas probadas en batalla que han ahorrado a mis equipos cientos de horas y prevenido innumerables dolores de cabeza en la integración.

La Fundación: Entendiendo REST Más Allá de la Palabra de Moda

Antes de sumergirnos en principios específicos, abordemos una verdad incómoda: la mayoría de las "APIs REST" en realidad no son RESTful. Son APIs HTTP con respuestas JSON, lo cual está bien, pero llamarlas REST es como llamar a una bicicleta una moto porque ambas tienen ruedas. La disertación original de Roy Fielding sobre REST esbozó seis restricciones, y la mayoría de las APIs violan al menos tres de ellas.

Aquí está lo que importa en la práctica: REST es un estilo arquitectónico que trata tu API como una colección de recursos, cada uno identificado por una URL, manipulada a través de métodos HTTP estándar. La belleza de este enfoque es su previsibilidad. Cuando veo GET /users/123, sé exactamente lo que hace sin leer la documentación. Cuando veo POST /users, sé que crea un nuevo usuario. Esta consistencia es el superpoder de REST.

En mi experiencia, los equipos que realmente entienden los principios REST envían APIs un 40% más rápido que aquellos que lo tratan como un simple requisito. ¿Por qué? Porque REST proporciona un modelo mental que guía las decisiones de diseño. ¿Debería ser este un nuevo endpoint o un parámetro de consulta? REST responde a eso. ¿Debería ser POST o PUT? REST te dice. Los principios no son restricciones, son barandillas que te mantienen en el camino hacia APIs mantenibles y escalables.

He revisado más de 200 diseños de API en mi carrera, y aquellos que envejecieron bien compartían una característica: respetaban el pensamiento orientado a recursos de REST. ¿Aquellos que se convirtieron en pesadillas de mantenimiento? Trataron REST como una sugerencia en lugar de un marco. Tu API vivirá más tiempo del que esperas—probablemente 5-7 años como mínimo en producción. Diseñala con esa longevidad en mente.

Principio 1: Los Recursos Son Sustantivos, No Verbos

Este principio parece obvio hasta que ves violaciones en el mundo real. Una vez heredé una API con endpoints como /getUser, /createOrder, y /deleteProduct. Cada operación era un verbo en la URL, haciendo que el método HTTP fuera redundante. La API tenía 127 endpoints que hacían lo que 23 endpoints orientados a recursos podrían haber hecho mejor.

Aquí está la regla: tus URLs deben representar cosas (recursos), y los métodos HTTP deben representar acciones sobre esas cosas. En lugar de POST /createUser, usa POST /users. En lugar de GET /getUserOrders, usa GET /users/123/orders. Esto no es pedantería—se trata de crear un modelo mental consistente que escale.

Considera la carga cognitiva. Con URLs basadas en verbos, los desarrolladores deben recordar nombres de endpoints arbitrarios. Con URLs basadas en recursos, siguen un patrón. En nuestra app fintech, redujimos el tiempo de incorporación para nuevos desarrolladores de 3 semanas a 1.5 semanas simplemente refactorizando a una correcta nomenclatura de recursos. La API se volvió autocomunicativa.

Por supuesto, hay excepciones. Acciones que no encajan perfectamente en operaciones CRUD—como POST /payments/123/refund o POST /orders/456/cancel—son aceptables. Estos son endpoints de estilo controlador, y están bien cuando la alternativa sería incómoda. La clave es usarlos con moderación y de manera consistente. En nuestra API actual, el 89% de los endpoints son operaciones puras de recursos, y el 11% restante son acciones de controlador claramente documentadas.

Al nombrar recursos, usa sustantivos plurales de manera consistente. /users no /user, /orders no /order. Sí, GET /users/123 devuelve un solo usuario, y eso puede sentirse gramaticalmente extraño, pero la consistencia triunfa sobre la gramática. He visto equipos perder horas debatiendo singular vs. plural; elige plural y sigue adelante.

Principio 2: Los Métodos HTTP Significan Lo Que Significan

HTTP nos brinda un rico vocabulario: GET, POST, PUT, PATCH, DELETE, y más. Cada uno tiene semánticas específicas, y respetar esas semánticas hace que tu API sea predecible y almacenable en caché. Sin embargo, veo regularmente APIs donde POST hace todo—crea, actualiza, elimina, incluso recupera datos. Esto es como usar un martillo para cada tarea de carpintería porque no quieres aprender otras herramientas.

Las solicitudes GET deben ser seguras e idempotentes. Segura significa que no modifican el estado del servidor. Idempotente significa que llamarlas múltiples veces produce el mismo resultado. Esto no es académico—habilita el almacenamiento en caché, lo que puede reducir la carga de tu servidor en un 60-80% para APIs con muchas lecturas. Cuando optimicé nuestra API de perfil de usuario implementando correctamente las semánticas de GET y el almacenamiento en caché HTTP, nuestros costos de servidor cayeron en $4,200 mensuales.

POST crea nuevos recursos. No es ni seguro ni idempotente—llamarlo dos veces crea dos recursos. PUT reemplaza un recurso completo y es idempotente—llamarlo diez veces tiene el mismo efecto que hacerlo una vez. PATCH actualiza parcialmente un recurso y debe ser idempotente. DELETE elimina un recurso y es idempotente. Estas distinciones importan para la lógica de reintento del cliente, las estrategias de almacenamiento en caché y las configuraciones del gateway de API.

Aquí tienes un ejemplo práctico de nuestra API de procesamiento de pagos. Inicialmente usamos POST para todo, incluidas las verificaciones de estado de pago. Cuando problemas de red hicieron que los clientes reintentaran solicitudes, creamos registros de pago duplicados. Después de refactorizar para usar GET para las verificaciones de estado e implementar claves de idempotencia adecuadas para las solicitudes POST, los pagos duplicados cayeron del 2.3% al 0.01% de las transacciones. Eso es dinero real ahorrado y confianza del cliente preservada.

Una pregunta común: ¿cuándo deberías usar PUT vs. PATCH? Usa PUT cuando el cliente envía la representación completa del recurso. Usa PATCH cuando el cliente envía solo los campos a cambiar. En la práctica, PATCH es generalmente más apropiado porque los clientes rara vez quieren enviar todos los campos. Nuestras analíticas muestran que el 94% de nuestras operaciones de actualización utilizan PATCH, y ha hecho que nuestras aplicaciones móviles sean más eficientes al reducir los tamaños de carga útil en un promedio del 73%.

Principio 3: Los Códigos de Estado Son Su Protocolo de Comunicación

Los códigos de estado HTTP son un lenguaje estandarizado para comunicarse...