Abres una app del tiempo y el pronóstico de mañana aparece en un segundo. No lo calculó tu teléfono: la app envió un mensaje corto al servidor del servicio meteorológico pidiendo los datos de una ciudad y recibió unas pocas líneas de datos simples, que convirtió en iconos y números. Lo mismo ocurre cuando el pago de una tienda online le pide a una empresa de pagos que cobre tu tarjeta, o cuando un compañero te dice: «usa su API, aquí tienes tu clave».
Este artículo sigue una llamada a la API desde la petición hasta la respuesta, con la salida real de nuestra propia prueba, y luego repasa los métodos, los códigos de estado, los tipos de API, las claves, los límites de solicitudes, el versionado y cómo proteger las claves.
¿Qué es una API?
Una API es la forma acordada en que un software le pide a otro datos o una acción. La sigla viene de application programming interface: «interfaz» porque es el punto de encuentro entre dos programas, y «programación» porque la usa el código, no una persona que hace clic en una pantalla.
Un cajero automático es una buena imagen cotidiana. Ofrece un menú corto y fijo (consultar saldo, retirar dinero, cambiar el PIN) y nunca ves la bóveda que hay detrás. Tu tarjeta y tu PIN prueban quién eres, un límite diario fija cuánto puedes sacar y un problema recibe un mensaje breve como «saldo insuficiente». Una API funciona igual: una lista fija de peticiones, una clave que identifica a quien llama, límites de uso y respuestas de error claras.
Los sistemas operativos y los navegadores también ofrecen API, pero en el uso cotidiano «una API» significa una API web: un servicio al que llamas por internet con HTTP, el protocolo que usa tu navegador para cargar páginas.
¿Cómo funciona una llamada a la API?
Una llamada a la API es una petición de un programa a una API más la respuesta que vuelve. Recorre siempre los mismos pasos:
- El cliente arma una petición. El cliente (una app, un script o un servidor) elige un método (qué hacer), un endpoint (la dirección de la operación), cabeceras (datos extra como la clave) y, en algunos métodos, un cuerpo con datos.
- La petición llega al servidor por una conexión HTTPS cifrada, después de que el DNS haya convertido el nombre del servidor en una dirección IP.
- El servidor comprueba a quien llama: ¿puede esta clave usar este endpoint y sigue dentro de sus límites?
- El servidor hace el trabajo, como leer una base de datos o iniciar un pago.
- El servidor responde con un código de estado que dice cómo fue, cabeceras y, por lo general, un cuerpo con los datos.
- El cliente lee la respuesta. Primero mira el código de estado y luego toma por su nombre los campos que necesita.
¿Cómo son una petición y una respuesta de una API?
Una petición es un método y un endpoint, cabeceras y a veces un cuerpo; una respuesta es un código de estado, cabeceras y casi siempre un cuerpo:
| Parte | En la petición | En la respuesta |
|---|---|---|
| Primera línea | Método + endpoint | Código de estado |
| Cabeceras | Clave, formato de datos | Formato de datos, límites |
| Cuerpo | Datos que enviar (opcional) | El resultado, a menudo JSON |
Puedes verlo con curl, una herramienta gratuita de línea de comandos para enviar peticiones web. JSONPlaceholder es una API pública de pruebas que no pide cuenta ni clave, así que es un lugar seguro para practicar:
curl -i https://jsonplaceholder.typicode.com/todos/1En nuestro equipo de pruebas, esto devolvió HTTP/1.1 200 OK, la cabecera Content-Type: application/json; charset=utf-8 y este cuerpo:
{
"userId": 1,
"id": 1,
"title": "delectus aut autem",
"completed": false
}La opción -i también imprime la línea de estado y las cabeceras, y sin una opción de método curl envía GET, que significa «leer». Un POST a /todos con un pequeño cuerpo JSON volvió como 201 Created con un nuevo "id": 201; esta API de pruebas solo finge guardar el registro, y eso es lo que la hace segura para practicar. Pedir /todos/999999, un registro que no existe, devolvió 404 Not Found.
El formato del cuerpo es JSON (JavaScript Object Notation): texto plano hecho de nombres y valores que casi cualquier lenguaje de programación sabe leer. Su estándar, el RFC 8259, exige UTF-8 entre sistemas y define el tipo de medio application/json, el valor de la cabecera de arriba. Las API más antiguas suelen responder en XML.
¿Qué métodos HTTP usan las API?
El método es el verbo de una petición: leer, crear, cambiar o eliminar. El RFC 9110, el estándar que define el significado de los mensajes HTTP, llama «seguros» a algunos métodos (solo leen) e «idempotentes» a otros (enviar la misma petición dos veces tiene el mismo efecto que enviarla una vez).
| Método | Tarea típica | Seguro | Idempotente |
|---|---|---|---|
GET | Leer un registro o una lista | Sí | Sí |
POST | Crear un registro, iniciar una acción | No | No |
PUT | Reemplazar un registro | No | Sí |
PATCH | Cambiar parte de un registro | No | No por defecto |
DELETE | Eliminar un registro | No | Sí |
La diferencia importa cuando una conexión se corta a mitad de camino. Repetir un GET no hace daño; repetir un POST puede crear un segundo pedido o un segundo pago. Por eso muchas API aceptan una clave de idempotencia junto con un POST, un valor único que le dice al servidor «si ya hiciste esta, no la vuelvas a hacer».
¿Qué significan los códigos de estado de una API?
El código de estado es el número de tres cifras al principio de cada respuesta, y su primera cifra indica quién es responsable: 2 significa éxito, 3 que el cliente debe dar otro paso, como seguir una redirección, 4 que la petición estaba mal y 5 que falló el servidor. Los códigos que más verás con las API:
200 OKy201 Created: la petición funcionó; 201 significa que se creó un registro nuevo.400 Bad Request: la petición está mal formada, a menudo por un campo que falta o un JSON roto.401 Unauthorized: no se envió una clave ni un token válidos.403 Forbidden: el servidor sabe quién eres, pero no tienes permiso para hacer esto.404 Not Found: el endpoint o el registro no existe.429 Too Many Requests: superaste el límite de solicitudes.500 Internal Server Error: el servidor falló al procesar la petición.
Una API bien hecha también explica el error en el cuerpo. Cuando llamamos sin token al endpoint /me de nuestra propia API, devolvió 401 Unauthorized, una cabecera www-authenticate: Bearer que nombra el esquema esperado y un cuerpo JSON con un código de error, un mensaje de una línea (Missing or malformed Authorization header) y un ID de petición para dar al soporte.
¿Qué tipos de API existen?
Las API web se diferencian sobre todo en la forma de las peticiones, y cuatro estilos cubren casi todo lo que te vas a encontrar:
| Tipo | Cómo pides | Uso típico |
|---|---|---|
| REST | Una dirección por recurso | La mayoría de las API web públicas |
| GraphQL | Un endpoint, tú listas los campos | Apps que necesitan datos flexibles |
| gRPC | Llamadas definidas en un archivo de esquema | Entre servicios internos |
| Webhook | El servicio te llama a ti | Avisos de eventos |
REST (representational state transfer) da a cada cosa su propia dirección, como /orders/42, y actúa sobre ella con los métodos HTTP de arriba. Cuando alguien dice «una API» sin más detalle, casi siempre se refiere a una API JSON de estilo REST. GraphQL envía todas las peticiones a un solo endpoint, y la consulta del cliente enumera exactamente los campos que quiere recibir. gRPC define cada llamada de antemano en un archivo de esquema y, por defecto, envía los datos como Protocol Buffers, un formato binario compacto.
Los webhooks invierten la dirección: en lugar de que tu programa pregunte «¿hay algo nuevo?» cada minuto, le das al servicio una URL tuya y él envía allí una petición cuando ocurre algo, como «pago recibido».
Las API también se diferencian por quién puede usarlas. Una API pública está abierta a cualquier desarrollador que se registre; una API de socios (partner), solo a empresas con contrato, como la integración para vendedores de un marketplace; y una API privada, solo a las apps y servicios de la propia empresa.
¿Qué es una clave de API y en qué se diferencia de un token?
Una clave de API es una cadena secreta larga que identifica al programa que llama a la API, como la tarjeta en el cajero automático. El servidor la comprueba en cada petición para decidir quién llama, qué puede hacer y qué límites se aplican, y suele seguir siendo válida hasta que la revocas.
Un token hace el mismo trabajo, pero normalmente se emite por menos tiempo o para un fin más concreto. OAuth 2.0 es el estándar detrás de la mayoría de las pantallas de «conectar tu cuenta»: apruebas una app en la propia página del servicio y la app recibe un token de acceso limitado a los permisos (scopes) que aprobaste, sin ver nunca tu contraseña. Muchos de esos tokens son tokens bearer, definidos en el RFC 6750: quien tenga uno puede usarlo, por eso viaja en la cabecera Authorization y nunca en la URL de una página.
| Método | Qué prueba | Uso típico |
|---|---|---|
| Clave de API | Qué programa o cuenta llama | Llamadas entre servidores |
| Token OAuth | Qué permitió un usuario a una app | Cuentas conectadas |
| Lista de IP permitidas | Desde dónde llega la llamada | Bancos, exchanges, B2B |
La clave se obtiene en la sección de desarrolladores o de API de tu cuenta en el sitio del servicio: la creas, marcas solo los permisos que necesita y la copias, porque muchos servicios muestran la clave completa una sola vez. Nuestra propia API, descrita en la sección Docs de este sitio, acepta un token bearer solo en la cabecera Authorization, nunca en la URL ni en una cookie, y cada token lleva sus scopes, así que un token de solo lectura no puede hacer un pedido.
¿Qué es un límite de solicitudes?
Un límite de solicitudes (rate limit) es el número de llamadas que alguien puede hacer en un tiempo dado, por ejemplo 60 peticiones por minuto por clave. Protege al servicio de la sobrecarga y evita que un solo usuario intensivo ralentice a todos los demás. Por encima del límite, la API responde 429 Too Many Requests hasta que se reinicia la ventana.
Muchas API informan de tu margen en las cabeceras de respuesta. La nuestra envía X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset con cada respuesta; estos nombres son una convención habitual, no un estándar fijo, así que revisa la documentación de cada API. Cómo manejar el error cuando aparece se explica en 429 Too Many Requests: qué es el error de rate limit.
¿Cómo se versionan y documentan las API?
Las API se versionan para que un cambio en el servidor no rompa los programas que ya las llaman. La forma más visible es poner la versión en la ruta, como en nuestra URL base https://api.proxynet.io/api/v1: los cambios incompatibles van a v2, y v1 suele seguir funcionando durante un periodo anunciado. Algunas API ponen la versión en una cabecera.
La documentación es el contrato de la API: cada endpoint con su método, sus parámetros, una respuesta de ejemplo y sus errores. Muchas API la publican en el formato de la OpenAPI Specification, un archivo JSON o YAML que describe una API HTTP tanto para personas como para herramientas (la versión 3.2.1 se publicó el 10 de septiembre de 2026). A partir de ese archivo, las herramientas pueden generar una referencia, crear código de cliente o montar un panel para probar las llamadas.
¿Cómo mantener segura una clave de API?
Trata una clave de API como una contraseña: quien la tenga puede actuar en tu nombre y, en una API de pago, gastar tu dinero. La mayoría de las filtraciones son sencillas:
- Claves en el código. Una clave pegada en un script acaba en un repositorio Git; guárdala en una variable de entorno o en un gestor de secretos.
- Claves en el código del front-end. Todo lo que se envía a un navegador o a una app móvil lo pueden leer sus usuarios; llama a la API desde tu servidor.
- Claves en URL. Las URL quedan en los registros del servidor y en el historial del navegador.
- Una clave para todo. Da a cada integración su propia clave con los mínimos permisos, para poder revocar una filtración por separado.
- Claves que nunca cambian. Rótalas de forma periódica y de inmediato tras una filtración: crea la nueva, cambia a ella y borra la antigua.
Del lado del proveedor, el API Security Top 10 de la OWASP Foundation recoge los fallos de API más comunes. El primero de su lista de 2023 es la autorización rota a nivel de objeto (Broken Object Level Authorization): un endpoint que devuelve el registro 42 a cualquiera que lo pida, sin comprobar que pertenece a quien llama.
¿En qué se diferencia una API del web scraping?
Una API devuelve los datos que un proveedor decide compartir, en un formato documentado y con límites por escrito; el web scraping descarga páginas hechas para personas y extrae los datos del HTML. La API es más estable cuando incluye los campos que necesitas, mientras que el scraping cubre lo que ninguna API ofrece, pero se rompe cuando cambia el diseño. Ambos se comparan, con los mismos datos obtenidos de las dos formas, en Web scraping vs. API: ¿cuál deberías usar?.
¿Por qué algunas API solo aceptan llamadas desde ciertas direcciones IP?
Algunas API comprueban de dónde viene una llamada, además de qué clave lleva. Bancos, exchanges de criptomonedas, marketplaces y muchos servicios de datos para empresas te dejan registrar direcciones IP para una clave, una lista de IP permitidas (IP allowlist), y rechazan las llamadas que llegan desde cualquier otro sitio, de modo que una clave robada no funciona en la máquina de otra persona.
Entonces tu programa necesita una dirección de salida fija, algo que no tienen las conexiones domésticas, los portátiles ni muchas funciones en la nube; las opciones se comparan en IP estática para API: cómo resolver el error de autorización.
Para entornos de prueba e integraciones que no manejan datos de pago ni de salud, los Proxies ISP dan a un script una IP dedicada que puedes registrar.
Los Proxies de centro de datos hacen lo mismo con una dirección de centro de datos. Ambos vienen con una restricción de sitios de destino por defecto, así que indicas el host de la API al hacer el pedido. Para integraciones de pagos y de salud, registra la dirección de tu propio servidor.
Dónde te encuentras con las API
- Apps del teléfono que obtienen el tiempo, los mensajes y los mapas de sus servidores.
- Pagos en tiendas online, donde la tienda llama a la API de una empresa de pagos para cobrar una tarjeta.
- Botones «Iniciar sesión con…», que comparten un perfil limitado con otro sitio.
- Apps de finanzas personales que muestran los saldos de varios bancos, cuando el banco ofrece una API para ello.
- Seguimiento de envíos en la página de una tienda, alimentado por la API de la empresa de mensajería.
- Funciones de IA dentro de otros productos, que envían tu prompt a un modelo de lenguaje a través de su API.
Errores frecuentes
- Ignorar el código de estado. Leer como datos el cuerpo de un
401o un429da resultados vacíos o erróneos. - Repetir un
POSTa ciegas. Puede crear un segundo pedido o pago; usa una clave de idempotencia si la API la ofrece. - Escribir la clave en el código. Se propaga a repositorios, capturas de pantalla y mensajes de chat.
- Insistir ante un 429. Los reintentos inmediatos te mantienen por encima del límite; espera a la hora de reinicio.
- Leer la documentación equivocada. Los campos y los límites cambian entre versiones; lee la documentación de la versión que llamas.
Guía de decisión
| Lo que necesitas | Qué hacer |
|---|---|
| Probar una API por primera vez | curl -i contra una API pública de pruebas |
| Dejar que los usuarios conecten su cuenta | OAuth, con los mínimos scopes |
| Enterarte de los eventos al momento | Un webhook en lugar de consultas periódicas |
| Mantenerte dentro de los límites | Lee las cabeceras del límite de solicitudes |
| Llamar a una API con lista de IP permitidas | Registra una IP fija |
| Guardar una clave | Variable de entorno o gestor de secretos |
Preguntas frecuentes
¿Qué significa API?
API son las siglas de application programming interface (interfaz de programación de aplicaciones): el conjunto de peticiones que un programa ofrece a otros, con las reglas sobre lo que debe contener cada petición y lo que devuelve. En la web, la palabra suele referirse a una API HTTP que responde en JSON.
¿Qué es una llamada a la API?
Una llamada a la API es una única petición que un programa envía a una API, junto con su respuesta. GET /todos/1, por ejemplo, pide un registro, y el servidor responde con un código de estado como 200 OK y el registro en JSON. Las API de pago suelen cobrar por llamada.
¿Qué es un endpoint de API?
Un endpoint es la dirección de una operación, formada por la URL base de la API y una ruta, como https://api.example.com/v1/orders. La misma ruta puede hacer cosas distintas según el método: GET lista los pedidos y POST crea uno.
¿Usar una API es gratis?
Depende del proveedor. Algunas API no piden ninguna clave, muchas son gratuitas hasta una cuota y después cobran por llamada, y algunas solo están abiertas a clientes o socios. El precio, los límites y lo que puedes hacer con los datos figuran en las páginas del propio proveedor.
¿Qué es un API gateway?
Un API gateway (pasarela de API) es un servidor situado delante de una o varias API que se encarga primero de las tareas comunes: comprobar claves, aplicar límites de solicitudes, dirigir cada ruta al servicio correcto y registrar la actividad. Quien llama ve una sola dirección, con muchos servicios detrás.
¿Necesito saber programar para usar una API?
Para probar una, no. Puedes llamar a una API pública con curl o desde el panel de pruebas de un sitio de documentación, y las herramientas de automatización sin código conectan API mediante formularios. Integrarla en tu propio producto sí requiere código, a menudo solo unas pocas decenas de líneas.
En resumen
Una API es un conjunto fijo de peticiones que un programa puede enviar a otro: un método y un endpoint salen con una clave o un token, y vuelven un código de estado y datos, normalmente en JSON. REST es el estilo más común; GraphQL, gRPC y los webhooks cubren las consultas flexibles, los servicios internos y los avisos de eventos. Mantén las claves fuera del código y de las URL, lee el código de estado antes que los datos y, cuando una API solo acepte llamadas desde direcciones registradas, dale una IP fija en la que confiar.




