¿Qué es una API?

Definición

Una API (Application Programming Interface, interfaz de programación de aplicaciones) es un contrato que define cómo un componente de software expone operaciones y datos a otros componentes: qué solicitudes acepta, con qué formato deben enviarse y qué respuestas devuelve. El consumidor de la API no necesita conocer la implementación interna; solo el contrato. A este principio se le llama encapsulamiento.

Existen APIs de bibliotecas (funciones que un programa llama dentro del mismo proceso), del sistema operativo y APIs web, que se consumen a través de la red. Esta guía trata las APIs web sobre HTTP, el tipo que usan las aplicaciones móviles, los sitios y las integraciones entre servicios.

El modelo cliente-servidor

Toda interacción con una API web sigue el mismo patrón:

1. El cliente (una app, un navegador, un script, otro servidor) inicia una petición (request).
2. El servidor la procesa: valida, consulta datos, ejecuta lógica.
3. El servidor devuelve una respuesta (response) con un código de estado y, normalmente, un cuerpo con datos.

HTTP es un protocolo sin estado (stateless): cada petición debe contener toda la información necesaria para procesarla (credenciales, parámetros, formato esperado). El servidor no «recuerda» peticiones anteriores salvo que la aplicación lo implemente explícitamente (sesiones, tokens, bases de datos).

Anatomía de una petición

Una petición HTTP tiene cuatro partes: método, URL, encabezados y, opcionalmente, cuerpo.

POST /v1/pedidos?notificar=true HTTP/1.1
Host: api.ejemplo.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Accept: application/json

{"producto": "SKU-1042", "cantidad": 2}

• Método (POST): la acción que se solicita sobre el recurso.
• URL: esquema (https), host (api.ejemplo.com), ruta (/v1/pedidos) y parámetros de consulta (?notificar=true). La combinación de host y ruta es el endpoint, el punto de acceso a un recurso.
• Encabezados (headers): metadatos de la petición. Content-Type declara el formato del cuerpo; Accept, el formato que el cliente espera recibir; Authorization, las credenciales.
• Cuerpo (body): los datos enviados, típicamente en JSON. Las peticiones GET no llevan cuerpo.

Anatomía de una respuesta

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/pedidos/8812

{"id": 8812, "estado": "recibido", "total": 1340.00}

La línea de estado incluye el código (201) y su frase (Created). Los encabezados describen la respuesta (formato, ubicación del recurso creado, políticas de caché) y el cuerpo contiene los datos.

Métodos HTTP y su semántica

La especificación de HTTP (RFC 9110) define el significado de cada método. Dos propiedades son clave al diseñar y consumir APIs: un método es seguro si no modifica el estado del servidor, e idempotente si repetir la misma petición produce el mismo efecto que hacerla una vez.

La idempotencia importa en redes poco confiables: si una petición PUT o DELETE falla por tiempo de espera, el cliente puede reintentarla sin riesgo. Un POST repetido puede crear duplicados; por eso muchas APIs de pago aceptan una clave de idempotencia (idempotency key) en un encabezado.

Códigos de estado

El código de estado resume el resultado. La primera cifra indica la clase:

La distinción entre 4xx y 5xx define quién debe corregir el problema: un 4xx exige cambiar la petición; un 5xx indica una falla del servicio, y reintentar más tarde puede resolverlo. 401 significa que no hay credenciales válidas; 403, que las hay pero no tienen permiso para esa operación.

Formatos de datos

El formato dominante es JSON (JavaScript Object Notation): texto estructurado en objetos (pares clave-valor), listas, cadenas, números, booleanos y null. Es legible para personas y se interpreta en cualquier lenguaje. Otras opciones son XML (sistemas heredados, facturación electrónica), formularios (application/x-www-form-urlencoded) y formatos binarios como Protocol Buffers.

El cliente indica qué formato envía con Content-Type y cuál prefiere recibir con Accept; a este intercambio se le llama negociación de contenido.

Estilos de API

Autenticación y seguridad

• API keys: una clave fija por cliente, enviada en un encabezado. Simple, adecuada para integraciones de servidor a servidor.
• Tokens Bearer y OAuth 2.0: credenciales temporales emitidas tras autenticar a un usuario o una aplicación; permiten limitar permisos (scopes) y revocar acceso.
• HTTPS (TLS): obligatorio. Cifra la comunicación; sin él, las credenciales viajan legibles.
• Límites de uso (rate limiting): el servidor restringe cuántas peticiones acepta por periodo y responde 429 al excederlo, frecuentemente con el encabezado Retry-After.
• CORS: política del navegador que impide a una página consumir APIs de otro dominio si el servidor no lo autoriza. No afecta a llamadas desde servidores o apps nativas.

Buenas prácticas de diseño REST

1. Recursos como sustantivos en plural: /pedidos, /pedidos/8812; la acción la expresa el método, no la ruta (POST /pedidos, no /crearPedido).
2. Códigos de estado precisos: 201 con encabezado Location al crear; 204 al eliminar; 422 cuando los datos no pasan la validación.
3. Versionado explícito: /v1/... o un encabezado de versión, para evolucionar sin romper a los clientes existentes.
4. Paginación en colecciones (?limit=50&cursor=...) para no devolver miles de registros en una respuesta.
5. Errores con estructura uniforme, por ejemplo el formato Problem Details (RFC 9457): tipo, título, código y detalle legible.
6. Documentación verificable: una especificación OpenAPI describe el contrato completo y permite generar documentación, clientes y pruebas. Lo veremos en el día 2.

Práctica: inspeccionar una API real

JSONPlaceholder es una API pública de pruebas. Con curl (incluido en Windows 10/11, macOS y Linux) puedes ver la petición y la respuesta completas:

curl -i https://jsonplaceholder.typicode.com/users/1

La opción -i muestra la línea de estado y los encabezados antes del cuerpo. Observa HTTP/1.1 200 OK y Content-Type: application/json. Después:

1. Solicita un recurso inexistente: curl -i https://jsonplaceholder.typicode.com/users/999 y verifica el 404.
2. Crea un recurso (la API lo simula sin guardarlo):

curl -i -X POST https://jsonplaceholder.typicode.com/posts -H "Content-Type: application/json" -d "{\"title\":\"Prueba\",\"userId\":1}"

Verás 201 Created y el recurso devuelto con un id asignado. Si prefieres una interfaz gráfica, Hoppscotch permite hacer las mismas peticiones desde el navegador.

Preguntas frecuentes

¿Qué es una API en palabras simples?

Es un acuerdo entre dos programas para pedirse datos o acciones y responderse con reglas claras. Funciona como el mesero de un restaurante: tu app pide, la API lleva el pedido al servidor y te trae la respuesta.

¿Para qué sirve una API?

Para que una app use datos o funciones de otro sistema sin saber cómo está hecho por dentro: el mapa en una app de transporte, el pago con tarjeta en una tienda en línea o el clima en tu teléfono.

¿Qué significan los códigos 200, 404 y 500?

Son códigos de estado HTTP. 200 indica que la petición salió bien; 404, que el recurso pedido no existe; y 500, que el servidor tuvo un error al procesarla.

¿Qué diferencia hay entre una API y un endpoint?

La API es el conjunto completo de operaciones que ofrece un sistema. Un endpoint es una dirección concreta dentro de ella, por ejemplo /usuarios/1, a la que se envía una petición.

Referencias

• RFC 9110, HTTP Semantics (IETF): definición de métodos, códigos de estado y encabezados.
• RFC 9457, Problem Details for HTTP APIs (IETF).
• MDN Web Docs: HTTP (Mozilla), referencia en español.