¿Solo POST? Pongamos fin a este absurdo debate sobre el diseño de APIs

Recientemente, me llamó la atención una discusión sobre si diseñar APIs usando "solo POST". Después de profundizar en este debate, descubrí que no solo el problema por el que la gente discute es irrelevante, sino que también expone el malentendido de muchos desarrolladores sobre la esencia del diseño de APIs. Hoy, profundicemos en las ideas centrales del diseño de APIs y veamos por qué este debate no debería existir en primer lugar.

La falacia de "solo POST"#

Aquellos desarrolladores que abogan por usar "solo POST" para reemplazar las especificaciones de la API RESTful claramente no han comprendido el punto más importante del diseño de APIs. Sus argumentos suelen incluir:

1. Simplificar el diseño: Un método puede manejar todo
2. Seguridad: los parámetros POST no aparecen en la URL
3. Flexibilidad: POST puede enviar cualquier estructura de datos

A primera vista, estos argumentos parecen tener algo de sentido. Pero en realidad, esta visión confunde la elección de los métodos HTTP con los estilos de diseño de APIs, dos niveles diferentes de problemas. POST es solo un método del protocolo HTTP, mientras que REST es un estilo de diseño de APIs.

La esencia del diseño de APIs#

Antes de discutir estilos de API específicos, necesitamos entender cuál es el propósito básico del diseño de APIs. Una buena API debería ser:

1. Clara y comprensible: Otros desarrolladores (incluido tu futuro yo) deberían poder entender intuitivamente el propósito de cada endpoint.
2. Consistente: Seguir ciertas especificaciones para reducir los costos de aprendizaje.
3. Extensible: Capaz de realizar fácilmente el control de versiones y la expansión de funcionalidades.
4. Eficiente: Considerar la eficiencia en términos de rendimiento y utilización de recursos.

API RESTful: Más que una elección de métodos HTTP#

La API RESTful es solo uno de muchos estilos de diseño de APIs, enfocado en recursos y operaciones sobre los recursos. Tomemos como ejemplo un sistema de blogs simple para ver cómo se diseña una API RESTful:

1. Obtener todos los artículos:

2. Obtener un artículo específico:

3. Crear un nuevo artículo:

4. Actualizar un artículo:

5. Eliminar un artículo:

En este ejemplo, podemos ver:

• La API está diseñada en torno al recurso "artículo".
• Se utilizan diferentes métodos HTTP para representar diferentes operaciones.
• La estructura de la URL es clara, indicando el recurso que se está operando.

Este enfoque de diseño hace que la API sea más intuitiva y autoexplicativa, lo que facilita que los desarrolladores entiendan la función de cada endpoint.

RPC: Comprendiendo el estilo de API detrás de "solo POST"#

El objetivo del diseño de APIs al estilo RPC (Remote Procedure Call) es hacer que las llamadas a servicios remotos parezcan tan simples como llamar a funciones locales.

Curiosamente, aquellos que abogan por "solo POST" pueden no darse cuenta de que en realidad están describiendo el estilo RPC.

En comparación con las APIs RESTful, el RPC se enfoca más en la operación en sí que en el recurso. Es por eso que las APIs al estilo RPC suelen usar una forma "verbo + sustantivo", como getProduct(productId) o createUser(userData).

En muchas implementaciones de RPC, todas las operaciones generalmente se envían mediante solicitudes POST al mismo endpoint, con la operación específica y los parámetros especificados en el cuerpo de la solicitud. Es por eso que la idea de "solo POST" se acerca más al RPC que al REST.

Por ejemplo, una solicitud "obtener producto" al estilo RPC basada en HTTP podría verse así:

Los marcos de trabajo modernos de RPC, como gRPC, proporcionan implementaciones más poderosas y eficientes. Utilicemos esto como un ejemplo para demostrar el estilo RPC:

Primero, definimos el servicio y el formato del mensaje (usando Protocol Buffers):

Luego, usar este servicio en un cliente Node.js es tan sencillo como llamar a una función local:

En este ejemplo al estilo RPC, podemos ver:

1. La definición del servicio enumera claramente todas las operaciones disponibles (en este ejemplo simplificado, GetArticle y CreateArticle).
2. Cada operación tiene tipos de solicitudes y respuestas claramente definidos.
3. El código del cliente parece una llamada a una función local asincrónica, usando await para esperar el resultado, lo que oculta aún más la complejidad de la comunicación en la red.
4. No hay necesidad de construir manualmente solicitudes HTTP o de analizar respuestas JSON.

Aunque la capa subyacente puede seguir usando HTTP/2 como protocolo de transporte, los marcos de trabajo RPC (como gRPC) proporcionan a los desarrolladores una capa de abstracción que hace que las llamadas remotas parezcan y se sientan como llamadas a funciones locales.

Por lo tanto, podemos ver que la mayoría de los debates sobre "solo POST" y APIs RESTful deberían ser esencialmente discusiones sobre estos dos estilos de APIs: REST y RPC. Sin embargo, lo clave es reconocer que estos dos estilos tienen cada uno sus escenarios de aplicación, y la elección debería basarse en las necesidades específicas del proyecto, no en la preferencia personal.

REST vs RPC: No hay superioridad o inferioridad absolutas#

Ahora que entendemos las diferencias entre REST y RPC, veamos sus respectivos escenarios de aplicación:

1. REST es adecuado para:
   • Aplicaciones orientadas a recursos (como sistemas de gestión de contenido, plataformas de blogs, sitios web de comercio electrónico)
   • Escenarios que requieren un buen soporte de caché (las solicitudes GET son naturalmente cacheables)
   • Proyectos que desean aprovechar la semántica HTTP (como usar códigos de estado apropiados)
   • APIs de cara al público que requieren una buena detectabilidad y auto-descripción
2. RPC es adecuado para:
   • Aplicaciones orientadas a acciones (como operaciones complejas de procesamiento de datos, control de flujos de trabajo)
   • Sistemas que requieren alto rendimiento y baja latencia (como sistemas de trading en tiempo real)
   • Comunicación entre microservicios internos (que pueden requerir un paso más flexible de parámetros)
   • Cuando las operaciones no pueden mapearse simplemente a operaciones CRUD (Crear, Leer, Actualizar, Eliminar)

La elección del estilo debe basarse en tus necesidades específicas. En algunos casos, incluso puedes usar una mezcla de estos dos estilos dentro del mismo sistema para satisfacer las necesidades de diferentes partes.

Conclusión#

1. La esencia del diseño de APIs radica en la claridad, consistencia, extensibilidad y eficiencia, no en ceñirse a un método o estilo en particular.
2. Tanto RESTful como RPC son paradigmas de diseño de APIs maduros. La elección entre ellos debe basarse en los requisitos del proyecto, no en la preferencia personal.
3. Si decides usar "solo POST", entonces, por favor, diseña tu API de acuerdo con el estilo RPC. Al igual que RESTful, es una especificación de API comúnmente utilizada en la industria, pero debe usarse en escenarios apropiados.
4. No te dejes confundir por los detalles técnicos superficiales. Lo que realmente importa es si tu API puede servir de manera efectiva a tus usuarios y necesidades comerciales.
5. Al diseñar APIs, dedica más tiempo a pensar en tu modelo de recursos, lógica de negocio y necesidades de los usuarios, en lugar de obsesionarte con qué método HTTP usar.

Desviemos nuestra atención de estos debates inútiles y enfoquémonos en diseñar APIs realmente excelentes. Después de todo, la tecnología está para resolver problemas, no para crearlos.