Qué es una API: la REST API explicada de forma sencilla

01Qué es una API: la analogía del camarero

La forma más conocida de explicar qué es una API es la analogía del restaurante. Usted es el cliente y la cocina es el sistema que guarda los datos. No puede entrar usted mismo en la cocina; mira la carta y le da el pedido al camarero. El camarero transmite la petición a la cocina y le trae el plato cuando está listo. En este escenario, el camarero es la API.

La carta es también la documentación de la API: le dice qué puede pedir, cómo pedirlo y qué recibirá a cambio. No puede pedir algo que no está en la carta; y tampoco necesita saber cómo funciona la cocina.

En el mundo del software, este orden aporta una gran comodidad. Una tienda online no necesita conocer el sistema interno de la empresa de transporte; le dice a la API de la empresa de transporte: «crea la etiqueta para este envío» y recibe la respuesta. Ambas partes pueden cambiar su estructura interna siempre que se respete el contrato de la API.

02¿Para qué sirve una API?

La respuesta a para qué sirve una API está escondida en casi todos los servicios digitales que usa a diario. Elegir una ubicación en un mapa dentro de una web, pagar con tarjeta, iniciar sesión con Google o ver el tiempo es, por detrás, una llamada a una API.

• Conecta los sistemas entre sí: la web, el marketplace, los envíos, la contabilidad y los pagos funcionan en un solo flujo.
• Reduce la introducción manual de datos: la información de pedidos, stock y facturas pasa de un sistema a otro por sí sola.
• Alimenta las aplicaciones móviles: la app del teléfono no obtiene los datos directamente de la base de datos, sino de la API.
• Permite usar servicios ya hechos: no hace falta escribir desde cero la infraestructura de pagos, mapas, SMS o correo.
• Ofrece acceso seguro: a la parte externa no se le abre toda la base de datos, sino solo las operaciones permitidas.

03¿Qué es una REST API?

Las API pueden diseñarse con estilos distintos; el más extendido en la web es el enfoque REST. La respuesta corta a qué es una REST API: un estilo de API que usa el protocolo HTTP, identifica cada dato con una dirección (recurso) y opera sobre esos recursos con métodos estándar.

En REST, todo es un recurso: productos, pedidos, clientes. Cada recurso tiene una dirección, y el método HTTP con el que acceda a ella determina lo que quiere hacer. Las respuestas suelen devolverse en formato JSON, un formato de texto que las personas pueden leer y que los programas procesan con facilidad.

¿Qué es un endpoint?

Un endpoint (punto final) es la dirección de una API en la que se realiza una operación concreta. Por ejemplo, /api/productos es el endpoint de la lista de productos y /api/productos/42, el del producto número 42. La documentación de una API es, en realidad, la lista de estos endpoints, de los métodos con los que se llaman y de lo que devuelven.

Códigos de estado

Con cada respuesta llega un código de estado HTTP que resume el resultado de la operación. 200 significa correcto, 201 registro creado, 400 petición errónea, 401 no autenticado, 403 sin permiso, 404 no encontrado, 429 demasiadas peticiones y 500 error del servidor. Una buena integración trata cada código por separado.

04Qué aspecto tiene una petición a una API

Una petición a una API consta básicamente de cuatro partes: la dirección, el método, las cabeceras (credenciales, tipo de datos) y, si hace falta, el cuerpo (los datos enviados). A continuación se ve una sencilla petición de lectura a una API pública de pruebas y una respuesta JSON típica.

Es posible enviar esta petición desde el terminal con curl, desde el navegador con JavaScript o desde el servidor con Python o Node.js; las reglas son las mismas, solo cambia la herramienta utilizada.

curl -s https://jsonplaceholder.typicode.com/posts/1 \
  -H "Accept: application/json"

{
  "userId": 1,
  "id": 1,
  "title": "...",
  "body": "..."
}

const yanit = await fetch("https://jsonplaceholder.typicode.com/posts/1");
if (!yanit.ok) throw new Error(`Hata: ${yanit.status}`);
const veri = await yanit.json();
console.log(veri.title);

05Seguridad de las API y autenticación

Salvo en las API públicas de pruebas, no se puede acceder a una API real sin demostrar quién es usted. Los métodos más habituales son la clave de API, los tokens de acceso de corta duración y los flujos de autorización como OAuth.

La seguridad no se limita a la autenticación. Una API bien diseñada da a cada usuario solo los permisos necesarios, valida los datos que recibe y limita el número de peticiones (rate limit) para evitar el uso indebido.

• No incluya nunca las claves de API en el código que llega al navegador ni en un repositorio público.
• Establezca siempre la conexión mediante HTTPS.
• Guarde las claves en variables de entorno y renuévelas periódicamente.
• Pida solo los permisos necesarios; si basta con el permiso de lectura, no solicite el de escritura.
• No filtre al exterior detalles del sistema interno en las respuestas de error.

06Ejemplos de integración por API

Una integración por API consiste en conectar dos o más sistemas mediante API para que intercambien datos de forma regular y automática. En el día a día de una empresa de e-commerce se ven casi todas estas conexiones.

Cuando entra un pedido, el stock se actualiza en todos los canales en los que se vende el producto; esto lo permite la integración con marketplaces. Al confirmarse el pedido, se obtienen de la empresa de transporte la etiqueta y el número de seguimiento; este paso corresponde a la integración de envíos. Y la factura se emite sola y se envía al cliente mediante la integración factura electrónica (el sistema turco de facturación electrónica).

En todas estas conexiones, lo difícil no es hacer la primera llamada. Las respuestas a preguntas como qué ocurre cuando el sistema de destino no responde, cómo evitar que el mismo pedido se procese dos veces o a quién se avisa cuando hay un error son lo que marca la diferencia entre una integración sólida y una conexión frágil.

¿API o webhook?

En una API, usted pregunta y la otra parte responde. En un webhook, en cambio, la otra parte le avisa por sí sola cuando ocurre un evento. En lugar de preguntar continuamente «¿hay algún pedido nuevo?», recibir un aviso cuando llega el pedido suele ser más eficiente; los detalles están en nuestro artículo qué es un webhook.

07¿Por dónde empezar a desarrollar una API?

Para aprender a usar una API, un buen comienzo es elegir una API pública de pruebas y enviar peticiones con curl o con una herramienta de pruebas de API. Leer las respuestas, interpretar los códigos de estado y probar los casos de error fija los conceptos con rapidez.

Si quiere escribir su propia API, tendrá que elegir un lenguaje de back-end. Para un comienzo rápido y legible, puede consultar el ejemplo de FastAPI de nuestro artículo qué es Python; y si prefiere avanzar con JavaScript, el ejemplo de Express del artículo qué es Node.js.

En cualquier caso, una buena API tiene tres rasgos en común: una documentación clara y actualizada, una nomenclatura coherente y respuestas de error previsibles. Si el desarrollador que vaya a usar una API puede leer la documentación y hacer su primera petición en pocos minutos, el diseño va por buen camino.