20 de septiembre de 2026

Qué es una API y una API REST: guía desde cero con ejemplos

Aprendé qué es una API y cómo funciona una API REST con ejemplos claros de endpoints, JSON, métodos HTTP, códigos de estado y seguridad básica.

Miniatura del video Qué es una API y una API REST desde cero — Explicación visual de APIs, REST, endpoints, JSON, métodos HTTP y códigos de estado · Ver en YouTube

Qué es una API, explicado fácil

API significa Application Programming Interface o interfaz de programación de aplicaciones. Es un conjunto de reglas que permite que dos piezas de software trabajen juntas sin que una necesite conocer todos los detalles internos de la otra.

Cuando una app del clima muestra el pronóstico, no necesita tener sus propios satélites ni calcular el tiempo. Puede solicitar los datos a una API meteorológica. Cuando una tienda cobra con Mercado Pago o PayPal, su sistema usa la API del proveedor para iniciar o confirmar el pago sin tener que construir una pasarela de pagos desde cero.

La API define, por ejemplo:

qué operaciones están disponibles;
qué datos hay que enviar;
qué formato deben tener esos datos;
qué respuesta se puede esperar;
qué ocurre si algo sale mal.

La analogía del restaurante, bien entendida

La comparación con un restaurante sirve para construir una primera idea:

Restaurante	API web
Carta	Documentación o contrato de la API
Cliente que hace el pedido	Cliente o aplicación que realiza una solicitud
Pedido	Request o petición
Cocina	Lógica del servicio, sistemas internos y, a veces, base de datos
Plato que vuelve	Response o respuesta

El mozo puede representar la interfaz que recibe un pedido y devuelve un resultado, pero una API no es una persona que “pasa información” por sí sola. Es la definición de la interacción; detrás puede haber un único servidor, varios servicios, una base de datos, una cola de mensajes o una integración externa.

Cómo funciona una API en una aplicación real

En muchas aplicaciones web, el flujo se parece a este:

Persona usuaria
  ↓
Frontend / cliente
  ↓ solicitud HTTPS
API y lógica del servidor
  ↓
Base de datos o servicio externo
  ↑
Respuesta de la API
  ↑
Frontend / cliente

Por ejemplo, al abrir la pantalla de productos de una tienda, el frontend puede hacer una solicitud a GET /api/productos. El servidor valida la solicitud, obtiene los productos de una base de datos y responde con los datos que el frontend necesita mostrar.

APIs locales y APIs remotas

La palabra API no se limita a internet. Una librería de Java tiene una API: sus clases y métodos públicos indican cómo usarla. El sistema operativo también ofrece APIs para interactuar con archivos, notificaciones, cámara, sonido o ventanas.

Cuando se habla de API web, normalmente se trata de una API remota: el cliente se comunica por una red con otro sistema, por lo general mediante HTTPS. Ese sistema puede estar en la nube, en un servidor de la empresa o incluso en otra computadora de una red local.

Tipo	Ejemplo	Cómo se comunica
API local	API de archivos de Java o API de notificaciones de un sistema operativo	Dentro de la app o del equipo
API web/remota	API de Mercado Pago, Google Maps o un backend propio	A través de una red, habitualmente con HTTPS

La diferencia importante no es si “está en la nube”, sino si la interacción ocurre dentro del mismo entorno o con otro sistema a través de la red.

Qué es una API REST

REST significa Representational State Transfer. No es un protocolo ni un lenguaje: es un estilo arquitectónico para diseñar sistemas distribuidos. En la práctica, muchas APIs web siguen sus ideas y usan HTTP para intercambiar solicitudes y respuestas.

Una API que usa HTTP no se vuelve REST automáticamente. Para acercarse a REST, suele organizar su interfaz alrededor de recursos y una interfaz uniforme:

GET    /api/productos          → obtener productos
GET    /api/productos/42       → obtener el producto 42
POST   /api/productos          → crear un producto
PATCH  /api/productos/42       → modificar parte del producto 42
DELETE /api/productos/42       → eliminar el producto 42

En este ejemplo, productos es el recurso y cada URL es un endpoint: una dirección concreta de la API a la que un cliente puede enviar una petición.

Principios prácticos de una API REST

Cliente y servidor separados: la interfaz cliente y la lógica del servicio evolucionan de forma independiente mientras respeten el contrato.
Sin estado entre solicitudes: cada petición debe incluir lo necesario para que el servidor la procese, como un token de autenticación cuando corresponda. No significa que la aplicación no guarde datos; significa que el servidor no depende de una sesión de conversación previa para interpretar la petición.
Recursos identificables: los recursos se representan con URIs, por ejemplo /api/usuarios/15.
Interfaz uniforme: los métodos HTTP y los códigos de estado expresan la intención y el resultado de manera consistente.
Respuestas que pueden indicar caché: cuando corresponde, una respuesta puede permitir que el cliente reutilice datos sin volver a pedirlos.

En proyectos cotidianos se suele decir “API REST” también para APIs que cumplen solo parte de estas convenciones. Eso es normal en la conversación técnica, pero conviene saber que REST es más que poner GET y POST en una URL.

Endpoint, request y response: las tres palabras que vas a ver siempre

Un endpoint es una ruta específica de una API. Un request es la petición que envía el cliente a esa ruta. Un response es la respuesta del servidor.

Supongamos que querés consultar un producto:

GET /api/productos/42 HTTP/1.1
Host: ejemplo.com
Accept: application/json

Una respuesta exitosa podría ser:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "nombre": "Teclado mecánico",
  "precio": 89.9,
  "stock": 12
}

GET indica que el cliente quiere obtener una representación del recurso.
/api/productos/42 identifica el recurso pedido.
200 OK comunica que la solicitud se resolvió correctamente.
application/json indica el formato del cuerpo de la respuesta.

JSON y XML: formatos de datos, no lenguajes universales

Para entenderse, el cliente y el servidor tienen que acordar cómo representar los datos. En APIs web actuales, JSON es muy común por ser compacto y fácil de manejar en JavaScript y muchos otros lenguajes.

{
  "nombre": "Kevin",
  "email": "kevin@ejemplo.com"
}

XML también sirve para representar datos y sigue vigente en integraciones empresariales, documentos y algunos servicios SOAP:

<usuario>
  <nombre>Kevin</nombre>
  <email>kevin@ejemplo.com</email>
</usuario>

JSON y XML son formatos de intercambio de datos. No son métodos HTTP ni una arquitectura. Aunque JSON sea habitual, una API también puede intercambiar formularios, archivos, HTML, texto, XML o formatos binarios según el caso.

Métodos HTTP: GET, POST, PUT, PATCH y DELETE

Los métodos HTTP expresan la intención de la petición. La siguiente tabla muestra el uso más habitual en una API orientada a recursos:

Método	Uso habitual	Ejemplo
`GET`	Consultar un recurso o colección	`GET /api/productos/42`
`POST`	Enviar datos para crear un recurso o ejecutar una acción	`POST /api/productos`
`PUT`	Crear o reemplazar por completo la representación de un recurso con URI conocida	`PUT /api/productos/42`
`PATCH`	Aplicar una modificación parcial	`PATCH /api/productos/42`
`DELETE`	Solicitar la eliminación de un recurso	`DELETE /api/productos/42`

Un error común es decir que POST siempre “sube información” o que PUT siempre “actualiza”. Son simplificaciones útiles al empezar, pero las semánticas importan:

POST se usa a menudo para crear recursos, pero también puede iniciar una operación, como procesar un pago.
PUT representa un reemplazo completo y es idempotente: repetir la misma solicitud debería dejar el recurso en el mismo estado final.
PATCH se usa cuando solo cambia una parte, por ejemplo el stock de un producto.
DELETE pide eliminar; que la API pueda devolver 204, 404 u otro resultado depende del diseño y del estado del recurso.

CRUD y HTTP: relacionados, pero no idénticos

CRUD resume operaciones sobre datos: crear, leer, actualizar y eliminar. HTTP proporciona métodos con semánticas más amplias. Una asociación común es POST para crear, GET para leer, PUT o PATCH para actualizar y DELETE para eliminar, pero no conviene convertirla en una regla rígida para todos los casos.

Ejemplo: crear un producto con una API REST

Para crear un producto, el cliente puede enviar una petición POST con un cuerpo JSON:

POST /api/productos HTTP/1.1
Host: ejemplo.com
Content-Type: application/json
Authorization: Bearer TOKEN_DE_EJEMPLO

{
  "nombre": "Mouse inalámbrico",
  "precio": 29.9,
  "stock": 25
}

Si la operación crea correctamente el recurso, una respuesta apropiada puede ser:

HTTP/1.1 201 Created
Location: /api/productos/43
Content-Type: application/json

{
  "id": 43,
  "nombre": "Mouse inalámbrico",
  "precio": 29.9,
  "stock": 25
}

El cliente no necesita saber cómo el servidor valida el producto, calcula impuestos o lo guarda. Solo necesita respetar el contrato público de la API.

Códigos de estado HTTP: cómo saber qué pasó

La respuesta de una API incluye un código de estado HTTP. No es la API quien “entiende” si algo salió bien: es el servidor quien devuelve un código para que el cliente pueda interpretar el resultado.

Familia	Significado	Ejemplos útiles
`2xx`	La solicitud fue procesada correctamente	`200 OK`, `201 Created`, `204 No Content`
`3xx`	Hace falta una acción adicional, generalmente una redirección	`301`, `302`, `304`
`4xx`	Hay un problema en la solicitud, autenticación o permisos del cliente	`400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, `409 Conflict`
`5xx`	El servidor no pudo completar una solicitud aparentemente válida	`500 Internal Server Error`, `503 Service Unavailable`

Los estados que más aparecen al consumir una API

Código	Cuándo suele aparecer
`200 OK`	La consulta o acción se completó y hay una respuesta para devolver.
`201 Created`	Se creó uno o más recursos.
`204 No Content`	La operación fue correcta, pero no hay cuerpo de respuesta.
`400 Bad Request`	La petición tiene sintaxis o formato inválido.
`401 Unauthorized`	Faltan credenciales válidas para autenticar la petición.
`403 Forbidden`	El cliente está autenticado, pero no tiene permiso para esa operación.
`404 Not Found`	El servidor no encuentra el recurso solicitado; no implica necesariamente que toda la API o ruta base “no exista”.
`422 Unprocessable Content`	La sintaxis puede ser válida, pero los datos no pasan una validación de negocio.
`500 Internal Server Error`	Ocurrió un fallo inesperado al procesar una solicitud que parecía válida.

Si alguien intenta crear un producto sin enviar el campo nombre, una API puede responder 400 o 422, según el contrato elegido. Un 500 no debería usarse para señalar un error de validación del usuario: normalmente indica que el servidor tuvo un problema no previsto.

REST, SOAP, GraphQL y gRPC: no todas las APIs se diseñan igual

REST es muy popular, pero no es la única forma de comunicar sistemas:

Tecnología o estilo	Idea general
REST	Estilo arquitectónico orientado a recursos; suele usarse sobre HTTP.
SOAP	Protocolo de mensajería con reglas formales; utiliza XML y continúa presente en algunas integraciones empresariales.
GraphQL	Lenguaje y sistema de consulta para APIs: el cliente solicita exactamente los campos que necesita.
gRPC	Framework de llamadas remotas que suele trabajar con contratos definidos mediante Protocol Buffers.

La elección depende del problema, el equipo, los clientes que consumirán la API, el tipo de datos y los sistemas con los que hay que integrarse. Para empezar a trabajar con backends y aplicaciones web, comprender HTTP, JSON y una API con estilo REST es una base excelente.

Errores comunes al aprender APIs

“Una API siempre conecta con una base de datos”

No necesariamente. Una API puede calcular algo, consultar otro servicio, enviar una notificación, trabajar con archivos o devolver información que ya está en memoria. La base de datos es un caso muy frecuente, no una condición obligatoria.

“REST es el protocolo HTTP”

HTTP es un protocolo de comunicación. REST es un estilo arquitectónico. Muchas APIs REST usan HTTP, pero son conceptos diferentes.

“JSON es el lenguaje de las APIs”

JSON es un formato para representar datos. La API puede estar implementada en Java, Node.js, Python, C# u otro lenguaje, y puede enviar JSON, XML u otros formatos.

“Un 404 significa que el backend está caído”

Un 404 Not Found indica que el servidor no encontró el recurso solicitado. Si el servidor no responde o está temporalmente indisponible, es más probable encontrarse con un problema de red, un 502, un 503 u otro error según la infraestructura.

“Cualquier API con GET y POST ya es REST”

Usar esos métodos es una buena práctica, pero REST incluye otras restricciones y decisiones de diseño. En el trabajo diario, lo importante es que el contrato sea claro, consistente, seguro y útil para sus consumidores.

Preguntas frecuentes sobre APIs

¿Qué es una API en palabras simples?

Es una interfaz con reglas para que una aplicación solicite una función o datos a otra y reciba una respuesta entendible.

¿Qué diferencia hay entre API y API REST?

API es el término general. Una API REST es una API que aplica, total o parcialmente, el estilo arquitectónico REST; en la web suele utilizar HTTP, recursos identificados por URL y respuestas con códigos de estado.

¿Necesito saber backend para usar una API?

No. Desde el frontend podés consumir APIs con herramientas como fetch, siempre que entiendas su documentación, la autenticación requerida y las reglas de seguridad. Para crear una API sí necesitás trabajar del lado del servidor o con una plataforma que lo resuelva.

¿Una API es lo mismo que un endpoint?

No. La API es el conjunto de operaciones y reglas expuestas. Un endpoint es una dirección o punto concreto dentro de esa API, como /api/productos/42.

Resumen: cómo pensar una API REST

Una API es un contrato de comunicación entre software.
Una API web permite que un cliente y un servidor intercambien solicitudes y respuestas por red.
REST es un estilo arquitectónico; no es sinónimo de HTTP ni de JSON.
Los endpoints identifican operaciones o recursos concretos de una API.
Los métodos HTTP expresan intención: consultar, crear, reemplazar, modificar o eliminar.
Los códigos de estado informan si la solicitud se procesó, falló por un problema del cliente o tuvo un error del servidor.
Una API útil también necesita documentación, autenticación, validación y un contrato coherente.

Para profundizar en la semántica oficial de HTTP, podés consultar el RFC 9110 del IETF. Si querés relacionar estas ideas con el recorrido de una aplicación, seguí con cómo funciona una base de datos: frontend, servidor y SQL.

Mirá la explicación completa y el ejemplo visual en YouTube.

En este artículo