APIs - Cheat Sheet

Anatomía de una URL REST

https :// api.ejemplo.com / v1 / usuarios / 42 / pedidos ? pagina=1 & limite=20

Esquema

Host

Versión

Recursos

Query params

Métodos HTTP

GET	idempotente	Obtener recurso(s). Sin cuerpo.
POST	—	Crear nuevo recurso.
PUT	idempotente	Reemplazar recurso completo.
PATCH	—	Modificar campos específicos.
DELETE	idempotente	Eliminar recurso.
HEAD	seguro	Como GET, solo cabeceras.

Petición → Respuesta

Petición (Request)

POST /v1/usuarios HTTP/1.1 Host: api.ejemplo.com Authorization: Bearer <token> Content-Type: application/json { "nombre": "Ana García", "email": "ana@mail.com" }

Respuesta (Response)

HTTP/1.1 201 Created Content-Type: application/json { "id": 8421, "nombre": "Ana García", "creado": "2026-05-28" }

Códigos de Estado

2xx — Éxito

200OK — solicitud exitosa

201Created — recurso creado

204No Content — sin cuerpo

3xx — Redirección

301Moved Permanently

304Not Modified (caché)

4xx — Error del cliente

400Bad Request — datos inválidos

401Unauthorized — sin auth

403Forbidden — sin permisos

404Not Found — no existe

429Too Many Requests — rate limit

5xx — Error del servidor

500Internal Server Error

502Bad Gateway

503Service Unavailable

Autenticación

API Key simple

Clave fija en cabecera o query param. Fácil de implementar, difícil de rotar.

X-API-Key: sk_live_abc123

Bearer / JWT recomendado

Token firmado con header.payload.signature. Expira y es sin estado.

Authorization: Bearer eyJhbG...

OAuth 2.0 delegado

Flujo de autorización con access_token + refresh_token. Estándar para apps de terceros.

Basic Auth evitar

user:pass en Base64. Solo con HTTPS. No recomendado en producción.

Authorization: Basic dXNlcjpwYXNz

Ciclo de vida de una petición

🖥 Cliente App / Browser

→

🔒 Auth Token / Key

→

🌐 Gateway Rate limit

→

⚙️ Servidor Lógica

→

🗄 Base de datos Datos

respuesta

Principios REST (Richardson Maturity)

🔗

Recursos URI

Sustantivos, no verbos

📡

Métodos HTTP

GET/POST/PUT/DELETE

🔀

HATEOAS

Links en respuesta

Cabeceras (Headers) comunes

Request

CabeceraDescripción

AuthorizationToken de autenticación

Content-TypeTipo de cuerpo enviado

AcceptTipo esperado en respuesta

X-Request-IDID único para trazabilidad

If-None-MatchETag para caché condicional

Response

Content-TypeTipo de la respuesta

Cache-ControlPolítica de caché

ETagVersión del recurso

X-RateLimit-*Límites de uso restantes

LocationURL del recurso creado (201)

Access-Control-*Política CORS

REST vs GraphQL

REST GraphQL

Múltiples endpoints Un solo endpoint

Datos fijos por ruta Consulta exacta

Over/Under-fetching Solo lo necesario

Cacheable por HTTP Caché compleja

Fácil de empezar Schema + resolvers

Sin tipado propio Tipado estricto

# GraphQL — pide lo que necesitas query { usuario(id: 42) { nombre pedidos { total } } }

Paginación & Filtros

Offset / Limit

GET /productos?pagina=2&limite=20 { "total": 340, "pagina": 2, "datos": [...] }

Cursor (recomendado)

GET /productos?cursor=eyJpZCI6NX0 { "siguiente": "eyJpZCI6MTB9", "datos": [...] }

Filtros y ordenación

GET /productos ?categoria=ropa &precio_max=100 &ordenar=precio_asc

Buenas prácticas

✓ Usa sustantivos en plural para recursos: /usuarios no /getUsuario

✓ Incluye siempre la versión en la URL: /v1/

✓ Usa el código de estado correcto, no siempre 200

✓ Devuelve errores claros con campo mensaje

✓ Implementa rate limiting y exponential backoff

✓ Usa siempre HTTPS en producción

✓ Documenta con OpenAPI / Swagger

✗ No expongas IDs secuenciales predecibles

✗ No guardes datos sensibles en query params (logs)

Content-Type más usados

application/json multipart/form-data application/xml text/plain application/octet-stream