¿Qué es REST? APIs RESTful explicadas

Aunque actualmente en la industria del software las APIs REST son bien conocidas y están ampliamente extendidas, en sus inicios, allá por años 2000, su aparición supuso un cambio sustancial en la manera en la que los servicios web se comunicaban. Hasta ese momento lo habitual era el uso de SOAP, un protocolo de intercambio de información a través de XML. Y a pesar de que hoy en día aún sigue usándose, REST es ahora prácticamente la elección por defecto cuando pensamos en desarrollar una nueva API.

¿Qué es una API REST?

REST es una arquitectura que se usa para desarrollar APIs web, en la que existen dos partes -el cliente y el servidor-, que se comunican entre sí para intercambiar información.

El conjunto de reglas REST fue inicialmente descrito por Roy Fielding en su tesis doctoral. A lo largo de los años ha ido haciendose más popular debido a su facilidad de uso, escalabilidad y flexibilidad.

Una API puede considerarse RESTful si se adhiere a los siguientes conceptos:

1. Interfaz uniforme. Las peticiones y las respuestas deben seguir un formato común. En el caso de las APIs REST HTTP, se hace uso de los métodos HTTP y de las URIs para identificar a cada recurso y la información se envía usando el formato de los mensajes HTTP.
2. Desacoplamiento. El cliente y el servidor actúan de forma completamente independiente. Todas las interacciones comienzan cuando el cliente inicia una petición y esperan a que el servidor envíe una respuesta.
3. Sin estado. Las peticiones al servidor desde el cliente deben contener toda la información necesaria para procesar esa petición. Esto significa que, por ejemplo, el servidor no debe guardar información sobre la sesión del cliente, sino que en este caso, es el cliente el que debería enviarle esta información al servidor en cada petición que se ejecute (por ejemplo, a través de las cabeceras).
4. Arquitectura en capas. La arquitectura REST permite un sistema de capas en el que cada una de estas capas sólo puede interactuar con la inmediatamente siguiente.
5. Caché. Siempre que sea posible, la información enviada o recibida debe almacenarse en caché. Para ello, el servidor tiene que especificar, mediante cabeceras, si la respuesta puede ser cacheada y durante cuánto tiempo.

Y te preguntarás, ¿qué es un recurso? Pues bien, es una entidad de datos a la que se puede acceder y manipular a través de una API REST. Por ejemplo, en una API sencilla que permite gestionar usuarios, usuario sería un recurso.

¿Cómo funciona una API REST?

El ciclo de interacción de una API REST es siempre iniciado por un cliente y se puede resumir así:

1. El cliente envía una solicitud HTTP al servidor. La solicitud incluye la URI del recurso y, en algunos casos, datos adicionales en el cuerpo de la solicitud.
2. El servidor procesa la solicitud según el método HTTP y la URI proporcionada. Realiza las operaciones necesarias en el recurso y puede devolver datos como respuesta.
3. El servidor responde con un código de estado HTTP que indica el resultado de la operación. También puede incluir datos relevantes en el cuerpo de la respuesta, como la representación del recurso solicitado.

¿Qué elementos contiene una llamada a una API REST?

Como hemos mencionado anteriormente la comunicación con una APIs REST se realiza a través de peticiones HTTP. La anatomía de una petición HTTP se compone de varios elementos. Cada uno de ellos atiende a un propósito, y entre todos informan servidor de cuál es la acción que se desea ejecutar.

• URI. También llamado API endpoint, especifica el path del recurso sobre el que se quiere actuar. Por ejemplo, /users.

• Método. Determina el tipo de acción a ejecutar en el servidor. Estos son los más comunes:

  • GET es utilizado para soliciar información.
  • POST es utilizado para enviar datos y/o crear nuevos recursos.
  • PUT y PATCH son utilizados para actualizar datos.
  • DELETE es utilizado para eliminar recursos.

  Para ilustrar estos conceptos, si estuviéramos desarrollando una API para gestionar usuarios podríamos crear los siguientes endpoints:

  Método HTTP	Path	Usado para
  GET	/users	Listar todos los usuarios
  POST	/users	Crear un nuevo usuario
  GET	/users/1	Obtener información sobre el usuario 1
  PUT	/users/1	Actualizar todos los atributos del usuario 1
  PATCH	/users/1	Actualizar algunos atributos del usuario 1
  DELETE	/users/1	Eliminar el usuario 1

• Headers (cabeceras). Pueden contener información como un token de autenticación, cookies o el formato en el que el cliente espera la respuesta.

• Body (cuerpo). Datos adicionales asociados con el recurso. Por ejemplo, en el caso de que estuviéramos creando un usuario, su información asociada: nombre, email, fecha de nacimiento, etc.

¿Qué elementos contiene una respuesta de una API REST?

• Código de estado. Es un código de tres dígitos que indica el resultado de la solicitud. Estos códigos se clasifican en cinco tipos, dependiendo si el servidor ha tenido éxito ejecutando el API endpoint o no. Estos son los rangos:

  • 100-199: indican que la petición fue recibida y se está procesando.
  • 200-299: indican la petición se ejecutó correctamente.
  • 300-399: indican que ha habido una redirección.
  • 400-499: indican que ha habido un error en el cliente.
  • 500-599: indican que ha habido un error en el servidor.

• Headers (cabeceras). Son metadatos que se envían junto con el cuerpo de la respuesta. Añaden información adicional como por ejemplo la fecha, descripción del servidor, tipo de formato de la respuesta, datos sobre la caché, entre otros.

• Body (cuerpo). Es el grueso de los datos que el servidor envía al cliente de vuelta. Por ejemplo, en el caso de que hayamos enviado una petición para crear un usuario, el servidor nos devolvería la información del objeto usuario.

¿Cómo puedo crear mi API REST en Hello API?

Desde Hello API puedes añadir muy fácilmente tu API REST y ejecutarla desde el navegador o compartirla con quien quieras a través de una URL a tu playground.

Para ello, el primer paso es registrarse.

Una vez completado el registro, en la barra lateral de la izquierda añade tantos endpoints como quieras. Para cada uno de ellos podrás configurar el método HTTP, la URL, las cabeceras, los parámetros y el cuerpo.

¿Cómo puedo ejecutar un API endpoint en Hello API?

Para ejecutar un endpoint, una vez configurados todos sus parámetros simplemente tendrás que hacer click en el botón “Run”. Esto hará que se envíe una petición al servidor. En el panel de la derecha verás los resultados de la ejecución.

¿Cómo puedo compartir mi API REST?

Hello API te permite compartir tu API con quien quieras. Cualquiera que tenga tu URL pública podrá ver y ejecutar los endpoints que previamente has definido. Pero tranquilo, no los podrán modificar.

Para compartir tu playground tan sólo tendrás que hacer click en la opción “Playground page” en el menú de la barra lateral izquierda. Se te abrirá tu URL pública en una pestaña nueva. ¡Copia esa URL y envíasela a quien quieras para mostrar tu maravillosa API!