Cómo diseñar APIs para defender cualquier sistema

📐 Resource-oriented (Google AIP)

Google prefiere APIs resource-oriented: las URLs son recursos, los métodos HTTP son verbos. POST /users mejor que POST /createUser.

📛 Naming conventions

• Recursos en plural: /users
• IDs en path: /users/{userId}
• Sub-recursos: /users/{id}/posts
• kebab-case en paths, camelCase en JSON
• Verbos custom como acciones: POST /videos/{id}:publish

🎯 Frase de oro al iniciar

"Voy a empezar identificando los recursos principales, luego las operaciones por recurso, y de ahí derivo los endpoints. Después hablo de paginación, errores, auth y rate limiting."

🟦 Cuándo elegir REST

• API pública, partners externos
• Necesitas caching agresivo (CDN)
• Clientes heterogéneos (curl, browsers)
• Recursos claros, CRUD-heavy
• Discoverability importa (OpenAPI)

🟩 Cuándo elegir gRPC

• Microservicios internos
• Latencia crítica (mobile, edge)
• Streaming bidireccional (chat, video)
• Polyglot teams (auto-gen clients)
• Schema evolution importante

🟪 Cuándo elegir GraphQL

• Frontends con muchas vistas distintas
• Reducir over-fetching móvil
• Aggregar múltiples backends (BFF)
• Schema-driven dev workflow
• Cuidado: N+1 queries, caching difícil

📡 gRPC streaming modes

• Unary: request → response (como REST normal)
• Server streaming: 1 request → N responses (feed, logs)
• Client streaming: N requests → 1 response (upload chunks)
• Bidirectional: N ↔ N (chat, gaming, real-time)

🇬 Tip Google-specific

Google publicó las API Improvement Proposals (AIP) en aip.dev — son sus reglas internas. Menciona resource-oriented design, standard methods (List, Get, Create, Update, Delete), field masks para updates parciales (en lugar de PATCH), y nombres pluralizados.

🔑 JWT structure

3 partes base64 separadas por puntos:

// Header
{ "alg": "RS256", "typ": "JWT" }

// Payload (claims)
{
  "sub": "user_42",
  "iss": "auth.example.com",
  "aud": "api.example.com",
  "exp": 1735689600,
  "iat": 1735686000,
  "scope": "read:users write:posts"
}

// Signature: RSA-sign(header.payload, private_key)

🛂 Authorization (RBAC vs ABAC)

• RBAC: Roles → Permissions. Simple. "Editor puede actualizar posts"
• ABAC: Atributos contextuales. "Puede leer SI: dueño OR rol = admin OR documento es público"
• ReBAC (Zanzibar): Google Drive style — relaciones (owner, editor, viewer) entre user y recurso. Spanner-backed.
• Tip: En Google interview, menciona Zanzibar si el problema involucra permisos complejos (Drive, Docs).

📡 SSE en 30 segundos

// Server response:
Content-Type: text/event-stream
Cache-Control: no-cache

event: update
data: {"price": 42.5}

event: update
data: {"price": 42.7}

🔌 WebSocket scaling

• Sticky LB (mismo cliente → misma instancia)
• Pub/Sub backplane (Redis/Pub-Sub) para fan-out
• Heartbeat (ping/pong) cada 30s
• Reconnect con exponential backoff
• Auth en query/cookie (no header en handshake)

🪝 Webhooks bien hechos

• HMAC signature en header (verifica origen)
• Endpoint idempotente + dedup por event_id
• Retry con exponential backoff (24h)
• Dead letter queue tras N fallos
• Devuelve 200 rápido, procesa async

🎬 Apertura: cualquier "diseña X"

"Voy a empezar identificando los recursos principales y las APIs por recurso. Después explico el flujo de escritura y lectura, dónde uso cache o colas, cómo manejo consistencia, seguridad, rate limits y observabilidad. Finalmente reviso tradeoffs y posibles bottlenecks."

🎯 Cierre fuerte (escala)

"El diseño funciona para escala moderada. Para 10× tráfico: separo ruta crítica de procesos asíncronos, agrego cache para lecturas calientes, particiono por userId o region, y mido p95/p99 para detectar bottlenecks. Plan B: read replicas y CDN edge caching."

⚡ Defender una decisión técnica

"Hay un trade-off entre [X] y [Y]. Yo elegiría [X] porque [razón concreta]. Si los requisitos cambian a [escenario], reconsideraría [Y]. Esto se monitorea con [métrica]."

🛡️ Cuando preguntan "¿y si falla?"

"Para failure de [componente]: timeout corto + retry con exponential backoff + circuit breaker. Si persiste, fallback a [degraded mode]. El cliente ve un error claro, no un cuelgue. Alertamos con SLO budget burn."