Cómo crear y consumir una API REST

Ninguna de las dos: es un estilo de arquitectura, es decir, un conjunto de convenciones sobre cómo diseñar una API usando HTTP para que sea predecible y fácil de usar. No se instala nada llamado REST ni depende de un lenguaje de programación en particular. Se apoya en cosas que ya existen —los métodos de HTTP, sus códigos de estado, las rutas— y define acuerdos sobre cómo combinarlos: los recursos se nombran con sustantivos, el método indica la acción, el código de estado informa el resultado. La consecuencia práctica es muy útil: una API REST hecha en cualquier lenguaje se ve y se consume igual, así que aprender estas convenciones una sola vez sirve para crear APIs en cualquier tecnología y para consumir cualquier API ajena sin tener que reaprender nada.

Esta guía cubre los conceptos de REST que son independientes del lenguaje: qué es una API REST, cómo se usan los métodos de HTTP, qué significan los códigos de estado, cómo se diseñan los recursos y las rutas, y cómo se consume una API desde un cliente. Son las ideas que sirven en cualquier tecnología. La guía de Node y Express, en cambio, lleva esos conceptos a una implementación concreta: cómo construir efectivamente una API con ese lenguaje y ese marco de trabajo, definiendo rutas, manejando peticiones y conectando una base de datos. La separación es intencional: entender primero las convenciones de REST hace que cualquier implementación posterior resulte evidente, porque solo cambia la sintaxis y no las ideas de fondo. Conviene leer esta primero y la de Node después.

Son números de tres cifras que la API devuelve para informar cómo salió la operación, y se agrupan por su primera cifra. Los que empiezan con dos indican éxito: el doscientos para una operación correcta, el doscientos uno cuando se creó un recurso, el doscientos cuatro cuando se hizo pero no hay contenido que devolver. Los que empiezan con cuatro indican un error del cliente, es decir, que el problema está en la petición: el cuatrocientos para una petición mal formada, el cuatrocientos uno cuando falta autenticación, el cuatrocientos tres cuando falta permiso, el cuatrocientos cuatro cuando el recurso no existe. Y los que empiezan con cinco indican un error del servidor, es decir, que la falla está del lado de la API. La distinción entre los del grupo cuatro y los del grupo cinco es la más útil para diagnosticar, porque dice de qué lado está el problema.

Porque en REST la acción ya la indica el método de HTTP, así que poner también un verbo en la ruta es redundante y rompe la convención que hace predecibles a las APIs. La idea central es que la ruta nombra el recurso —usando sustantivos, normalmente en plural, como barra pedidos— y el método dice qué hacer con él: leer, crear, modificar o borrar. Así, la combinación de método y ruta describe completamente la operación de forma consistente. Cuando en cambio se ponen verbos en las rutas, como barra crear-pedido o barra borrar-pedido, cada API termina inventando sus propios nombres, se pierde la predecibilidad y quien la consume tiene que leer toda la documentación para adivinar cómo funciona cada operación, en lugar de deducirla a partir de las convenciones.

JSON es un formato de texto para representar datos estructurados —objetos con campos y valores, listas, números, textos— que es a la vez fácil de leer para las personas y fácil de procesar para los programas. Se volvió el formato estándar de intercambio en las APIs por varias razones: es ligero, no depende de ningún lenguaje en particular aunque nació del mundo de JavaScript, y prácticamente todos los lenguajes traen herramientas para convertir sus propios datos a JSON y viceversa. En una API REST, los datos que se envían al crear o modificar un recurso, y los que la API devuelve en sus respuestas, viajan habitualmente en JSON. Al enviarlo, conviene indicar en la cabecera correspondiente que el contenido es de ese tipo, para que el servidor sepa cómo interpretarlo; omitir ese detalle es una causa común de errores al consumir o construir APIs.

Con dos cuidados centrales. El primero es comprobar siempre el código de estado de la respuesta antes de confiar en sus datos: una petición puede fallar por muchos motivos, y leer el cuerpo sin verificar primero que la respuesta fue exitosa hace que el programa se rompa ante el primer error de la API. Conviene manejar explícitamente los casos de error según el código recibido. El segundo cuidado es no exponer credenciales en el cliente: si la API requiere una clave o un token, ese secreto no puede ir escrito en el código que corre en el navegador, porque cualquiera puede leerlo inspeccionando la página; en esos casos las peticiones autenticadas se hacen desde un servidor propio que guarda el secreto, no directamente desde el navegador. Con esas dos precauciones, más el uso de conexiones cifradas, el consumo de una API es robusto y seguro.