Guía completa para el diseño de RESTful API: conceptos y mejores prácticas

10min

Las API RESTful han calado fuertemente en las arquitecturas de las aplicaciones modernas.  No es difícil realizarlas, ya que básicamente consisten en responder a las operaciones básicas del CRUD con datos en JSON. Sin embargo, ¿podrías decir si tu API está bien diseñada? Si no tienes certeza, sigue con nosotros y conoce los conceptos clave y las mejores prácticas para diseñar una API RESTful robusta y fácil de usar.

Índice

¿Qué es una API RESTful y cómo funciona?

Para empezar conviene dar algunas definiciones básicas, por si alguien todavía anda perdido por ahí. Una API REST (que viene de las siglas Representational State Transfer) es un servicio web (web service) que sigue los principios de la arquitectura REST. 

REST es un estilo o unas guías de arquitectura para API que utilizan el protocolo HTTP para permitir la comunicación entre diferentes capas de la aplicación. Una API RESTful es un API que respeta REST para permitir a los clientes realizar operaciones como crear, leer, actualizar y eliminar recursos utilizando los verbos HTTP como GET, POST, PUT y DELETE.

Conceptos clave de RESTful API

Para que nadie se pierda, antes de profundizar en los conceptos técnicos, queremos aportar una visión general de la arquitectura REST y sus principios fundamentales para la construcción de API.

Arquitectura REST: fundamentos y principios

REST se basa en varios principios fundamentales que vamos a resumir y que sirven para crear aplicaciones entendibles pero además escalables y flexibles, facilitando su mantenimiento y evolución.

  • Cliente / servidor: Indica la separación de capas de la aplicación. Esto es positivo porque permite que cada parte evolucione de manera independiente.
  • Stateless: En REST, cada petición del cliente debe contener toda la información necesaria para ser procesada, sin depender del estado almacenado en el servidor. Por decirlo de otra manera, no hay sesiones.
  • Cacheabilidad: Las respuestas deben ser cacheables siempre que sea posible, lo que ayuda a mejorar el rendimiento.
  • Interfaz uniforme: Se debe usar siempre una interfaz consistente, lo que facilita la interacción entre sistemas, ya que todas las peticiones siguen siempre un formato predecible.

Métodos HTTP: GET, POST, PUT, DELETE y otros

En REST son fundamentales los métodos del protocolo HTTP, que sirven para definir la acción que se quiere realizar sobre un recurso. El uso correcto de estos métodos resume la carga de las solicitudes y mejora la consistencia y claridad del API.

Los métodos a los que nos referimos son los siguientes:

  • GET: Recuperar información de un recurso.
  •  POST: Crear un nuevo recurso.
  • PUT: Actualizar un recurso existente o crear uno si no existe.
  • PATCH: Parecido a PUT, realizar una actualización, pero en este caso parcial.
  • DELETE: Eliminar un recurso.

Recursos y URI: cómo estructurar endpoints

Otros dos conceptos que debemos conocer son los recursos (resource) y los URI:

  • Un recurso es cualquier entidad a la que se pueda acceder mediante la API, como usuarios, clientes, pedidos o productos.
  • Los URI (Uniform Resource Identifiers) identifican de forma única cada recurso. Por ejemplo: /usuarios/{id} es el URI para acceder al usuario con un «id» determinado.

Statelessness: la importancia del estado en REST

Como hemos dicho, uno de los principios básicos de la arquitectura REST es «statelessness». Esto significa que cada petición debe contener toda la información necesaria para procesarla, sin requerir que el servidor almacene datos de sesión que permitan identificar futuras peticiones.

Dado que el servidor no almacena el estado del cliente entre peticiones, se facilita la escalabilidad del servicio, ya que es perfectamente asumible que varios servidores puedan atender peticiones de un mismo API sin problemas.

Representaciones: JSON, XML y otros formatos

Los recursos en una API RESTful se representan en diferentes formatos, siendo el más común JSON en la actualidad, dado que permite generalmente un poco menos de peso en el dato que debe ser transferido y los lenguajes web tienden a gastar menos recursos para procesarlo.

Sin embargo, también es perfectamente posible tener un API REST que devuelva datos en XML. Lo importante es que los datos puedan transferirse mediante texto plano por el protocolo HTTP.

Diferencia entre una API REST y una API RESTful

Existe a menudo cierta confusión cuando abordamos los términos API REST y API RESTful. De hecho, a menudo se utilizan indistintamente para referirse a la misma cosa.

La diferencia es bastante sutil. Mientras que REST es un conjunto de principios arquitectónicos, cuando decimos que un API es RESTful queremos mencionar que se ha implementado siguiendo estos principios de manera fiel. Para que nos entendamos: una API RESTful es una API que sigue los principios REST de manera estricta, mientras que una API REST puede que no cumpla todas las convenciones necesarias para ser considerada RESTful.

Mejores prácticas para el diseño de RESTful API

A continuación, pasamos a abordar las mejores prácticas para garantizar que nuestra API sea escalable, segura y fácil de usar por todos los clientes.

Uso correcto de los métodos HTTP

No podemos dejar de utilizar los métodos HTTP de la manera esperada. Esto ayudará a mantener la coherencia y claridad del servicio web. 

Además hay algunas cosas importantes y es que los métodos GET, PUT y DELETE deben ser idempotentes, lo que significa que llamar varias veces al mismo endpoint debe tener el siempre el mismo efecto que llamarlo una única vez.

Versionado de API: cómo gestionar versiones

Es inevitable que nuestro API evolucione para dar respuesta a las nuevas demandas de los clientes. Para evitar problemas de compatibilidad a lo largo de la evolución del API debemos aplicar políticas de versionado. Una buena práctica es incluir la versión en la URL, por ejemplo, /v1/usuarios. 

Es importante que estas decisiones se tomen desde el principio para evitar problemas en un medio plazo de tiempo.

Seguridad en API REST: autenticación y autorización

Obviamente, las API REST deben aportar la necesaria seguridad para el acceso a la información sensible o confidencial. Existen muchas estrategias para autenticación y autorización de los clientes. Una muy común es OAuth, que es un protocolo avanzado y muy completo. Sin embargo, habitualmente se usa también JWT (JSON Web Tokens), ya que son capaces de aportar la suficiente seguridad en la mayoría de las aplicaciones.

Paginación y filtrado de resultados

Cuando trabajamos con grandes cantidades de datos es importante ofrecer  paginación y filtrado para optimizar el rendimiento de la API, su versatilidad y las transferencias. A la vez, estaremos descongestionando al cliente, ya que no enviaremos demasiada información de respuesta. 

Utiliza parámetros consistentes para la paginación a lo largo de todos los recursos.

Manejo de errores: códigos de estado HTTP adecuados

Otro punto fundamental en el desarrollo de las API REST es el uso adecuado de los códigos de estado de las respuestas HTTP. Estos códigos nos ofrecen una información detallada sobre el resultado de la petición y suelen usarse de manera transversal en todos los proyectos, por lo que los desarrolladores prácticamente no tienen ni que preguntar.

Los códigos más importantes son estos:

  • 200 OK: La petición fue exitosa.
  • 201 Created: Un nuevo recurso fue creado.
  • 400 Bad Request: La petición tiene errores de sintaxis y no es procesable.
  • 401 Unauthorized: El cliente no está autenticado para usar o acceder a cierta información.
  • 404 Not Found: El recurso no fue encontrado.
  • 500 Internal Server Error: Hubo un problema en el servidor, generalmente un error no tratado.

Además de los códigos HTTP también es habitual incluir mensajes detallados en el cuerpo de la respuesta. Gracias a esos mensajes los clientes pueden dar información más precisa a los usuarios, como por ejemplo los motivos por los que un formulario no se aceptó.

Cómo documentar una RESTful API

Aunque el uso de convenciones como las que hemos mencionado ya ayuda bastante, la documentación de una API RESTful es esencial para informar a los desarrolladores su modo de funcionamiento. Por ejemplo, es necesario saber qué esquema tienen los datos que vamos a recibir o debemos enviar.

Herramientas para la documentación de API (Swagger, Postman, etc.)

Lo más normal es acudir a herramientas que nos ayuden a documentar nuestras API de manera clara y accesible. 

Swagger (ahora conocida como OpenAPI) es la más popular. Permite declarar la documentación en el propio código y genera una interfaz interactiva para la lectura y trabajo con los recursos.

Aunque no es tan habitual, también podríamos usar Postman para documentar un API, gracias al propio trabajo realizado a la hora de probar las API. Esto es útil para compartir y colaborar fácilmente con otros desarrolladores.

Creación de una guía clara para usuarios y desarrolladores

Además de la documentación más técnica, es ideal proporcionar ejemplos prácticos con descripciones detalladas del funcionamiento de los endpoints. Debemos explicar cómo autenticarse contra el API, cómo generar las llaves de uso, etc.

Implementación y pruebas de RESTful API

Una vez que hemos diseñado y documentado nuestra API debemos implementarla en un lenguaje y realizar las pruebas pertinentes, para asegurarnos de que funcione correctamente en producción.

Cómo implementar una API RESTful en diferentes lenguajes

Podemos implementar una API RESTful en prácticamente cualquier lenguaje de programación backend. Sin embargo, existen algunos lenguajes populares para acometer un API, como JavaScript (con Node.js y Express o frameworks como Nest); PHP (con frameworks como Laravel o Symfony); Java (generalmente con Spring Boot) o Python (usando frameworks como Flask o Django).

Pruebas automatizadas para asegurar la calidad de la API

Tenemos que realizar también las correspondientes pruebas automatizadas para asegurar que nuestra API se comporte como se espera. Cada lenguaje y framework ofrece generalmente una herramienta para pruebas, JUnit (para Java), Pytest (para Python), Jest (para JavaScript) o PhpUnit (para PHP).  

Gracias a esos frameworks de pruebas resultará más fácil escribir las pruebas unitarias. Además será interesante también realizar las pruebas de integración, que verifican la funcionalidad de nuestros endpoints, asegurando que se mantengan sin errores a medida que la API evoluciona.

Buenas prácticas para el mantenimiento y actualización de API

Para el mantenimiento de una API debemos seguir prácticas que nos aseguren el buen funcionamiento frente a actualizaciones, ya sean ampliaciones y mejoras o de corrección de errores o parches de seguridad. 

En estos casos es importante mantener un ciclo de versionado claro, evitar cambios disruptivos que puedan romper la compatibilidad con los clientes que vienen usando el API, así como monitorear el rendimiento y uso de la API para identificar posibles cuellos de botella.

Fernán García de Zúñiga

Artículos relacionados

Productos relacionados: