Cómo funciona una API — explicación completa

Qué la compone, cómo se le envían peticiones y qué mirar cuando trabajas con ellas

Una API web es básicamente un contrato entre dos programas: uno pide, otro responde. Las APIs modernas usan HTTP y JSON, pero pueden trabajar con XML, form-data, multipart y otros formatos. Lo importante es entender las piezas y cómo encajan para poder diseñar, probar o consumir una API correctamente.

Componentes básicos

• Endpoint / Ruta: la URL donde escuchan las peticiones. Ej: /api/users, /posts/123.
• Métodos HTTP: definen la intención: GET, POST, PUT, PATCH, DELETE.
• Cabeceras (Headers): metadata de la petición: Content-Type, Accept, Authorization, etc.
• Cuerpo (Body): datos que envías en POST o PUT, típicamente JSON: {"name":"Ana"}.
• Códigos de estado: respuesta del servidor: 200, 201, 400, 401, 404, 500, etc.
• Respuesta: normalmente JSON o XML con la data solicitada o el mensaje de error.

Métodos HTTP en detalle

Los más usados y su semántica:

• GET → pedir un recurso, no debe cambiar nada, idempotente.
• POST → crear o enviar datos que el servidor procesa, no idempotente en general.
• PUT → reemplazar un recurso entero, idempotente (mismo request varias veces, mismo resultado).
• PATCH → actualizar parcialmente, no siempre idempotente.
• DELETE → borrar un recurso. Normalmente idempotente.

Formatos de cuerpo y cabeceras clave

• Content-Type: application/json → cuerpo en JSON.
• Content-Type: application/x-www-form-urlencoded → formularios clásicos.
• Content-Type: multipart/form-data → uploads de archivos.
• Accept → qué formatos acepta el cliente, ej Accept: application/json.

Ejemplo simple de petición y respuesta

GET /api/users/42 HTTP/1.1
Host: api.ejemplo.com
Accept: application/json
Authorization: Bearer eyJ...

RESPONSE 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Ana",
  "email": "ana@ejemplo.com"
}

Autenticación y autorización

Dos cosas distintas: autenticar = demostrar quién eres; autorizar = qué puedes hacer. Los métodos comunes:

• API keys: token simple en header o query, fácil de usar, no es la opción más segura por sí sola.
• Bearer tokens / JWT: token firmado que incluye info (claims), se envía en Authorization: Bearer ....
• OAuth2: flujo para delegar acceso (ideal para APIs públicas que trabajan con terceros).
• Mutual TLS: cliente y servidor se autentican con certificados, usado en entornos muy seguros.

Estados y códigos de error

Los servidores deben devolver códigos claros, y mensajes con la mínima info necesaria:

• 2xx → éxito (200 OK, 201 Created).
• 3xx → redirección.
• 4xx → error del cliente (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found).
• 5xx → error en el servidor (500 Internal Server Error).

CORS y políticas de origen

CORS regula qué orígenes pueden hacer peticiones desde el navegador. Si un API no configura CORS correctamente, puede exponer datos a dominios no deseados. Cabeceras clave: Access-Control-Allow-Origin, Access-Control-Allow-Credentials, Access-Control-Allow-Methods.

Idempotencia y seguridad en métodos

Diseñar APIs pensando en idempotencia ayuda a evitar efectos no deseados. También es importante validar inputs, escapar datos y no confiar en la entrada del cliente sea cual sea el método.

Paginación, filtrado y búsqueda

Cuando una colección es grande, la API debe soportar paginación y filtros. Patrones comunes:

• ?page=2&per_page=50
• ?limit=20&offset=40
• Filtros por campos: ?status=active&sort=-created_at

Caching y rendimiento

Cabeceras como Cache-Control, ETag y Last-Modified ayudan a reducir carga. Para APIs públicas, usar CDNs y limitar tamaño de respuestas es clave.

Rate limiting y protección

Limitar peticiones por IP o por token evita abusos. Responder con 429 Too Many Requests y un header con el reset time es una práctica habitual.

Versionado

Mantener versiones evita romper clientes: ejemplos comunes /v1/users o usar cabeceras Accept: application/vnd.ejemplo.v2+json.

HATEOAS y REST vs GraphQL

REST es arquitectura basada en recursos y HTTP. HATEOAS añade enlaces en las respuestas para descubrir acciones. GraphQL es alternativa que permite pedir exactamente los campos que quieres en una sola petición, con sus pros y contras.

Buenas prácticas de diseño

• Documentación viva (OpenAPI/Swagger).
• Validación estricta de inputs y límites en tamaño de payloads.
• Mensajes de error útiles pero concisos (no leaks de info sensible).
• Logs y trazabilidad, correlación por request-id para debug.
• Principio de mínimo privilegio en tokens y permisos.

Ejemplos prácticos

Crear un recurso (POST):

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

{
  "name": "Juan",
  "email": "juan@ejemplo.com"
}

# Response
201 Created
Location: /api/users/101

Actualizar parcialmente (PATCH):

PATCH /api/users/101 HTTP/1.1
Content-Type: application/json

{ "email": "juan.nuevo@ejemplo.com" }

# Response
200 OK
{ "id":101, "name":"Juan", "email":"juan.nuevo@ejemplo.com" }

Errores comunes a evitar

• Dejar endpoints sin autenticación por error.
• Exponer demasiada información en los errores (stack traces).
• No validar tamaños o tipos de datos (riesgo de DoS o inyección).
• No rotar o revocar claves y tokens comprometidos.

Resumen práctico

La API es el contrato entre clientes y servidor. Diseñarla bien implica pensar en métodos correctos, seguridad, control de acceso, documentación y rendimiento. Si lo montas pensando en escenarios reales, evitas sorpresas. Si consumes una API, revisa documentación, límites, formatos y comportamiento ante errores.

← Volver al blog