APIs REST: qué son y cómo las usamos realmente

Si llevas un tiempo trabajando en desarrollo web, seguramente hayas oído hablar de las APIs REST.

Es más, es bastante probable que hayas utilizado alguna sin saber exactamente qué había detrás.

Cuando una aplicación móvil consulta tus pedidos, cuando una web carga productos sin recargar toda la página o cuando una aplicación necesita comunicarse con otro servicio, normalmente hay una API haciendo de intermediaria.

Y aquí es donde aparece REST.

Después de más de una década trabajando en desarrollo web y pasando por diferentes tecnologías de backend, hay conceptos que con el tiempo empiezas a ver de otra manera.

Las APIs son uno de ellos.

Cuando estás empezando pueden parecer algo bastante abstracto: endpoints, métodos HTTP, JSON, autenticación, códigos de respuesta…

Pero cuando empiezas a trabajar con ellas de verdad, la idea básica es bastante sencilla.

Una aplicación necesita hablar con otra.

Así que en este artículo no quiero hacer una explicación académica de REST.

Prefiero hacerlo como me habría gustado que me lo explicaran cuando estaba empezando: con un ejemplo y hablando también de algunas de las cosas que, por mi experiencia trabajando con aplicaciones web, considero importantes cuando diseñamos una API.

Vamos a imaginar una tienda online

Supongamos que tenemos una tienda online.

El usuario entra y ve los productos, añade cosas al carrito, consulta sus pedidos y finalmente realiza una compra.

Todo eso parece una única aplicación desde fuera.

Pero por dentro tenemos diferentes piezas.

Por un lado está el frontend, que es lo que ve el usuario:

  • Los productos.
  • El carrito.
  • El perfil.
  • Los pedidos.
  • El proceso de compra.

Y por otro tenemos el backend, que se encarga de toda la parte que el usuario no ve:

  • Base de datos.
  • Usuarios.
  • Productos.
  • Pedidos.
  • Pagos.
  • Autenticación.

Podríamos tener algo parecido a esto:

┌─────────────────┐
│    Frontend     │
│                 │
│ Vue / React     │
└────────┬────────┘
         │
         │ HTTP
         ▼
┌─────────────────┐
│       API       │
│                 │
│ /api/products   │
│ /api/users      │
│ /api/orders     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Backend     │
│                 │
│ PHP / Java /    │
│ Node / etc.     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    Database     │
└─────────────────┘

El frontend no necesita saber cómo está montada nuestra base de datos.

No necesita saber si utilizamos MySQL, PostgreSQL o cualquier otra tecnología.

Simplemente necesita poder decir:

Oye, dame los productos.

Y el backend se encarga del resto.

Ahí es donde entra nuestra API.

Entonces, ¿qué es realmente una API?

Si tuviera que explicárselo a alguien que está empezando, probablemente le diría que una API es el mecanismo que permite que diferentes partes de una aplicación puedan comunicarse entre ellas.

Por ejemplo, el frontend puede hacer:

GET /api/products

Y el backend podría responder:

{
    "data": [
        {
            "id": 1,
            "name": "Teclado mecánico",
            "price": 89.99
        },
        {
            "id": 2,
            "name": "Ratón inalámbrico",
            "price": 49.99
        }
    ]
}

El frontend recibe esos datos y los muestra.

Parece bastante sencillo, ¿verdad?

Porque realmente lo es.

Lo que ocurre es que cuando empiezas a añadir usuarios, permisos, errores, paginación, filtros, autenticación y cientos de endpoints, la cosa empieza a complicarse.

Y ahí es donde una API bien diseñada empieza a marcar la diferencia.

¿Y qué significa REST?

REST son las siglas de Representational State Transfer.

El nombre suena bastante más complicado de lo que necesitamos para empezar.

Una API REST utiliza principalmente HTTP y trabaja con recursos.

Por ejemplo:

/api/products
/api/users
/api/orders

Tenemos productos, usuarios y pedidos.

Y utilizamos los métodos HTTP para indicar qué queremos hacer con ellos.

Por ejemplo:

GET /api/products

Quiero obtener productos.

POST /api/products

Quiero crear un producto.

GET /api/products/15

Quiero obtener el producto número 15.

PUT /api/products/15

Quiero actualizar el producto número 15.

Y:

DELETE /api/products/15

Quiero eliminarlo.

Una de las cosas que más me gusta de este enfoque es precisamente esa sencillez.

La URL representa el recurso y el método HTTP indica qué queremos hacer con él.

No necesitamos inventarnos una URL diferente para cada operación.

Vamos a llevarlo a algo más real

Volvamos a nuestra tienda.

Imaginemos que estoy trabajando en el panel de administración y tengo una pantalla donde aparecen todos los productos.

Cuando entro en la pantalla, el frontend hace:

GET /api/products

El backend consulta la base de datos y devuelve los productos.

Hasta aquí, sencillo.

Pero ahora pulso:

«Crear producto»

El frontend podría enviar:

POST /api/products
Content-Type: application/json

con:

{
    "name": "Teclado mecánico",
    "price": 89.99,
    "stock": 25
}

El backend recibe la petición.

Comprueba los datos.

Hace las validaciones necesarias.

Guarda el producto.

Y responde:

201 Created

junto con algo parecido a:

{
    "id": 125,
    "name": "Teclado mecánico",
    "price": 89.99,
    "stock": 25
}

El frontend recibe la respuesta y actualiza la interfaz.

El usuario probablemente ni siquiera se entera de todo lo que acaba de ocurrir.

Y eso es precisamente una API funcionando.

No hay magia.

Hay una aplicación haciendo una petición, otra procesándola y una respuesta viajando de vuelta.

GET, POST, PUT y DELETE

Estos cuatro métodos aparecen constantemente cuando trabajamos con APIs.

GET

Para obtener información:

GET /api/products

POST

Para crear algo nuevo:

POST /api/products

PUT

Para actualizar un recurso:

PUT /api/products/125

DELETE

Para eliminarlo:

DELETE /api/products/125

Hay más métodos HTTP, evidentemente, pero estos cuatro son los que más vamos a encontrarnos en una API REST.

Y una vez que entiendes esta lógica, muchas APIs empiezan a resultar bastante más fáciles de leer.

Una pequeña manía personal: /getUsers

Aquí tengo una pequeña manía.

A veces me encuentro APIs con cosas como:

/api/getUsers
/api/createUser
/api/deleteUser

Y técnicamente pueden funcionar perfectamente.

Pero si estamos intentando diseñar una API REST, personalmente prefiero:

GET /api/users
POST /api/users
DELETE /api/users/25

¿Por qué?

Porque la operación ya está expresada mediante HTTP.

Si estoy haciendo un GET, no necesito que la URL me diga getUsers.

Puede parecer una diferencia insignificante.

Y probablemente lo sea cuando tienes tres endpoints.

El problema llega cuando tienes cincuenta, cien o más.

Ahí empiezas a agradecer que alguien haya seguido un criterio coherente.

Una API debería ser predecible.

Y esto es algo que he aprendido con el tiempo: cuando tienes que trabajar con una API que ha desarrollado otra persona, agradeces muchísimo que no tengas que adivinar cómo funciona cada endpoint.

Los códigos HTTP también cuentan cosas

Otra parte que me parece importante son los códigos de respuesta.

Por ejemplo:

200 OK

Todo ha ido bien.

Si acabamos de crear algo:

201 Created

Si buscamos un producto que no existe:

404 Not Found

Si no estamos autenticados:

401 Unauthorized

Y si estamos autenticados pero no tenemos permisos:

403 Forbidden

Esto último es especialmente importante.

No es lo mismo:

No sé quién eres.

que:

Sé quién eres, pero no puedes hacer esto.

Parece una diferencia pequeña, pero en una aplicación real importa bastante.

Después de trabajar con APIs durante años, una de las cosas que más valoro es que los errores sean claros.

Un 500 Internal Server Error no debería ser nuestra respuesta para absolutamente todo.

Si el usuario ha enviado datos incorrectos, deberíamos poder indicarlo.

Si no tiene permisos, deberíamos indicarlo.

Si el recurso no existe, deberíamos indicarlo.

Cuando una aplicación crece, estas pequeñas decisiones terminan teniendo bastante importancia.

¿Por qué utilizamos tanto JSON?

Cuando trabajamos con APIs web es muy habitual que los datos viajen en JSON.

Por ejemplo:

{
    "id": 125,
    "name": "Teclado mecánico",
    "price": 89.99
}

Es fácil de leer y prácticamente cualquier lenguaje moderno puede trabajar con él.

Pero hay una aclaración que merece la pena hacer:

REST no significa JSON.

REST es un estilo arquitectónico.

JSON es simplemente uno de los formatos que podemos utilizar para representar los datos.

En la práctica se ha convertido en una opción muy habitual y por eso es normal encontrárselo constantemente cuando trabajamos con APIs.

El frontend no debería saber cómo funciona nuestra base de datos

Esta es probablemente una de las cosas que más valoro de trabajar con APIs.

Podríamos tener:

Vue
 ↓
API REST
 ↓
Backend
 ↓
PostgreSQL

Y el frontend no debería tener que preocuparse de que detrás estamos utilizando PostgreSQL.

Mañana podemos optimizar consultas.

Cambiar parte de la lógica.

Modificar tablas.

Incluso sustituir alguna pieza de nuestra infraestructura.

Mientras mantengamos el contrato de la API, el frontend debería poder seguir funcionando.

Y esto se vuelve cada vez más importante a medida que el proyecto crece.

Por experiencia, cuanto más grande se hace una aplicación, más importante es que cada parte tenga unas responsabilidades bastante claras.

Si todo sabe demasiado sobre todo, cualquier cambio acaba teniendo consecuencias en lugares que ni siquiera esperabas.

El contrato de una API

Podemos pensar en el contrato como las reglas que hemos establecido para comunicarnos con nuestra API.

Por ejemplo:

GET /api/products/125

devuelve:

{
    "id": 125,
    "name": "Teclado mecánico",
    "price": 89.99
}

El frontend sabe que ese endpoint existe y sabe qué estructura tiene la respuesta.

Ahora imaginemos que un día cambiamos:

"price": 89.99

por:

"cost": 89.99

Desde nuestro punto de vista puede parecer un cambio pequeño.

Pero para el frontend puede significar:

«Acabas de romperme la aplicación».

Y esto es algo que quizá no preocupa demasiado cuando estás empezando.

Cuando empiezas a trabajar con aplicaciones separadas, sí.

Los cambios pequeños en una API pueden tener consecuencias bastante grandes.

Por eso conviene pensar un poco antes de modificar el contrato.

¿Y qué pasa cuando tenemos miles de productos?

Al principio podemos tener 50 productos y hacer:

GET /api/products

Perfecto.

Pero imaginemos que pasan dos años y ahora tenemos 50.000.

No parece demasiado buena idea devolver los 50.000 cada vez que alguien entra en la página.

Aquí entra en juego la paginación.

Podríamos hacer:

GET /api/products?page=1&limit=20

Y devolver solamente 20 productos.

Después:

GET /api/products?page=2&limit=20

Y obtenemos los siguientes.

También podemos añadir filtros:

GET /api/products?category=monitors

Búsquedas:

GET /api/products?search=keyboard

O incluso ordenar:

GET /api/products?sort=price

Son detalles que al principio pueden parecer secundarios.

Pero cuando empiezas a trabajar con datos reales, rápidamente dejan de serlo.

Y entonces aparece la autenticación

Volvamos otra vez a nuestra tienda.

Cualquiera puede consultar:

GET /api/products

Pero no queremos que cualquiera pueda hacer:

DELETE /api/products/125

Necesitamos saber quién está haciendo la petición y qué puede hacer.

Aquí podemos utilizar diferentes mecanismos dependiendo del proyecto:

  • Sesiones.
  • Tokens.
  • JWT.
  • OAuth.
  • API keys.

No existe una solución universal.

Y aquí hay dos conceptos que conviene separar:

Autenticación

¿Quién eres?

Autorización

¿Qué puedes hacer?

Puedo estar perfectamente identificado como usuario y aun así no tener permiso para eliminar productos.

Parece obvio cuando lo lees, pero separar bien ambas cosas evita bastantes problemas de diseño.

Una API también tiene que saber decir «no»

Esta es otra de esas cosas que parecen sencillas hasta que empiezas a construir una aplicación real.

¿Qué pasa si alguien intenta crear un producto sin nombre?

¿Y si pone un precio negativo?

¿Y si intenta acceder a un producto que no existe?

¿Y si el servidor tiene un problema?

Tenemos que decidir qué respuesta devolver.

Por ejemplo:

{
    "message": "El precio debe ser mayor que 0"
}

junto con:

400 Bad Request

La idea es que quien consume nuestra API pueda entender qué ha ocurrido y actuar en consecuencia.

Para mí, una API no debería limitarse a decir:

Ha fallado.

Debería intentar decir:

Ha fallado esto, por esta razón y aquí tienes información suficiente para saber qué hacer.

Cuanto más crece una aplicación, más se agradece esto.

No hace falta complicarlo todo

Y aquí vuelvo a una idea que comentaba en el artículo anterior sobre PHP.

Últimamente parece que cualquier aplicación necesita microservicios, Kubernetes, colas, eventos, cinco bases de datos y una arquitectura que necesita tres diagramas para explicar cómo funciona.

A veces sí.

Pero muchas veces no.

Una API REST puede ser perfectamente sencilla:

Frontend
   ↓
API
   ↓
Backend
   ↓
Base de datos

Y funcionar perfectamente.

Una cosa que he aprendido con los años es que la arquitectura debería responder a las necesidades del proyecto y no al revés.

No tiene mucho sentido montar una infraestructura gigantesca para una aplicación pequeña.

Y tampoco tiene sentido intentar mantener una aplicación enorme como si fuera un proyecto de fin de semana.

La dificultad debería venir del problema que tenemos que resolver, no de nuestra necesidad de utilizar todas las tecnologías que conocemos.

REST tampoco sirve para absolutamente todo

REST es muy útil, pero no es la única forma de comunicación entre aplicaciones.

Tenemos, por ejemplo:

  • GraphQL.
  • WebSockets.
  • gRPC.
  • Colas de mensajes.
  • Eventos.

Cada tecnología tiene sus propios casos de uso.

Si necesitamos comunicación en tiempo real, WebSockets puede tener mucho sentido.

Si diferentes servicios necesitan comunicarse internamente, podemos utilizar mensajería.

Si queremos que el cliente pueda solicitar exactamente los datos que necesita, GraphQL puede ser interesante.

Por eso intento no empezar un proyecto pensando:

«Voy a utilizar X porque es lo que se lleva ahora».

Prefiero empezar por:

«¿Qué problema tenemos que solucionar?»

Y después decidir qué tecnología tiene sentido.

Puede parecer una diferencia pequeña, pero creo que cambia bastante la forma de plantear un proyecto.

Entonces, ¿qué hace que una API sea buena?

Para mí no es que tenga 200 endpoints ni que utilice la tecnología más moderna.

Una buena API debería ser, sobre todo, predecible y fácil de utilizar.

Que las URLs tengan sentido.

Que los métodos HTTP se utilicen de forma coherente.

Que los errores sean claros.

Que la autenticación esté bien planteada.

Que no devolvamos información innecesaria.

Que exista documentación.

Y, sobre todo, que otro desarrollador pueda utilizarla sin tener que preguntarnos cada cinco minutos cómo funciona.

De hecho, creo que esta es una prueba bastante buena.

Dale la documentación de tu API a otro desarrollador y deja que intente utilizarla.

Si necesita preguntarte constantemente qué hace cada endpoint, probablemente haya algo que mejorar.

Y si puede empezar a trabajar con ella sin que tengas que sentarte a explicarle todo, probablemente vas por buen camino.

Conclusión

Las APIs REST pueden parecer bastante abstractas cuando empiezas a leer sobre ellas.

Pero cuando las llevas a un ejemplo real, la idea básica es bastante sencilla.

Tenemos una aplicación que necesita hablar con otra.

Utilizamos HTTP.

Tenemos recursos.

Utilizamos métodos como GET, POST, PUT y DELETE.

Devolvemos información, normalmente en JSON.

Y establecemos unas reglas para que ambos lados sepan cómo comunicarse.

Lo complicado no es conseguir que una API funcione.

Lo complicado es conseguir que siga siendo fácil de entender y mantener cuando el proyecto empieza a crecer.

Y ahí es donde, al menos desde mi experiencia, está una de las partes realmente interesantes del desarrollo backend.

Porque después de años trabajando con diferentes tecnologías, cada vez valoro más las soluciones que son fáciles de entender.

No necesariamente las que tienen más piezas.

No las que utilizan más tecnologías.

Y tampoco las que quedan mejor en un diagrama.

Al final una API hace algo bastante sencillo:

permite que diferentes partes de una aplicación puedan hablar entre ellas sin tener que conocer todos los detalles de lo que ocurre al otro lado.

Y cuando está bien diseñada, casi ni te das cuenta de que está ahí.

Para mí, esa suele ser una buena señal.

Media: 0,00/5 0 votos