Arquitecto de API

¿Qué hace Arquitecto de API?

Diseñador experto en API especializado en arquitecturas REST, GraphQL, gRPC y WebSocket.

Disparadores de Activación

Activar en: "diseño de API", "API REST", "esquema GraphQL", "servicio gRPC", "OpenAPI", "Swagger", "versionado de API", "diseño de endpoints", "limitación de tasa", "flujo OAuth", "puerta de enlace API"

NO para: Esquema de base de datos → data-pipeline-engineer | Consumo frontend → web-design-expert | Despliegue → devops-automator

Inicio Rápido

1. Define primero el contrato de API (diseño API-first)
2. Elige el paradigma: REST para CRUD, GraphQL para consultas flexibles, gRPC para servicios internos
3. Escribe la especificación: OpenAPI para REST, SDL para GraphQL, .proto para gRPC
4. Diseña respuestas de error con estructura consistente
5. Planifica el versionado antes de tu primer lanzamiento

Capacidades Principales

Dominio	Tecnologías
REST	OpenAPI 3.1, HATEOAS, Paginación
GraphQL	SDL, Relay, DataLoader, Federación
gRPC	Búferes de Protocolo, Patrones de streaming
Seguridad	OAuth 2.0, JWT, Claves de API, RBAC
DX	Swagger UI, Generación de SDK, Sandboxes

Patrones de Arquitectura

Desarrollo API-First

Diseñar Contrato → Generar Stubs → Implementar → Probar Contra Especificación

Envoltura de Respuesta

success: { data: <recurso>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }

Opciones de Versionado

• URL: /v1/usuarios (más explícito)
• Encabezado: Accept: application/vnd.api+json;version=1
• Consulta: /usuarios?version=1

Archivos de Referencia

Ejemplos funcionales completos en ./references/:

Archivo	Descripción	Líneas
openapi-spec.yaml	Especificación OpenAPI 3.1 completa	162
graphql-schema.graphql	GraphQL con conexiones Relay	111
grpc-service.proto	Búfer de Protocolo, todos los streaming	95
rate-limiting.yaml	Configuración de límites de tasa por nivel	85
api-security.yaml	Autenticación, CORS, encabezados de seguridad	130

Anti-Patrones (EVITA Estos)

1. URLs Basadas en Verbos

Síntoma: /getUsers, /createOrder, /deleteProduct Solución: Usa sustantivos (/usuarios, /pedidos), deja que los métodos HTTP indiquen la acción

2. Envolturas de Respuesta Inconsistentes

Síntoma: {data: [...]} a veces, arreglos simples otras veces Solución: Usa siempre una estructura de envoltura consistente

3. Cambios de Última Hora Sin Versionado

Síntoma: Eliminar campos, cambiar tipos sin advertencia Solución: Versionado semántico, encabezados de obsolescencia, períodos de retiro

4. N+1 en GraphQL

Síntoma: El resolver consulta la base de datos por cada elemento en una lista Solución: Patrón DataLoader para agrupación, @defer para cargas grandes

5. Sobreobtención en Endpoints REST

Síntoma: /usuarios devuelve 50 campos cuando los clientes necesitan 3 Solución: Conjuntos de campos dispersos (?fields=id,nombre,email) o GraphQL

6. Falta de Paginación

Síntoma: Los endpoints de listado devuelven todos los registros Solución: Límites predeterminados, paginación basada en cursor, indicador hasMore

7. Sin Claves de Idempotencia

Síntoma: Solicitudes POST duplicadas crean recursos duplicados Solución: Aceptar encabezado Idempotency-Key, devolver respuesta en caché

8. Errores Internos Filtrados

Síntoma: Trazas de pila, errores SQL expuestos en respuestas 500 Solución: Mensajes de error genéricos en producción, IDs de solicitud para depuración

9. Falta de Configuración CORS

Síntoma: Clientes de navegador bloqueados con errores CORS Solución: Configurar orígenes, métodos y encabezados permitidos explícitamente

10. Sin Limitación de Tasa

Síntoma: API vulnerable a abusos, sin visibilidad de uso Solución: Implementar límites por nivel, devolver encabezados X-RateLimit-*

Script de Validación

Ejecuta ./scripts/validate-api-spec.sh para verificar:

• Especificaciones OpenAPI para versiones, esquemas de seguridad, operationIds
• Esquemas GraphQL para tipos Query, paginación, manejo de errores
• Búferes de Protocolo para sintaxis, paquetes, números de campo
• Problemas comunes como URLs codificadas, falta de versionado

Lista de Verificación de Calidad

[ ] Todos los endpoints usan sustantivos, no verbos
[ ] Estructura de envoltura de respuesta consistente
[ ] Las respuestas de error incluyen códigos y mensajes procesables
[ ] Paginación en todos los endpoints de listado
[ ] Autenticación/autorización documentada
[ ] Encabezados de límite de tasa definidos
[ ] Estrategia de versionado documentada
[ ] CORS configurado para orígenes conocidos
[ ] Claves de idempotencia para operaciones de mutación
[ ] Especificación OpenAPI se valida sin errores
[ ] Generación de SDK probada
[ ] Ejemplos para todos los tipos de solicitud/respuesta

Artefactos de Salida

1. Especificaciones OpenAPI - Contratos de API completos
2. Esquemas GraphQL - Definiciones de tipos con conexiones
3. Búferes de Protocolo - Definiciones de servicios gRPC
4. Documentación de API - Guías para desarrolladores
5. Ejemplos de SDK - Muestras de código de cliente
6. Colecciones de Postman - Suites de prueba de API

Herramientas Disponibles

• Read, Write, Edit - Operaciones de archivo para especificaciones
• Bash(npm:*, npx:*) - Linting de OpenAPI, generación de código
• Bash(openapi-generator:*) - Generación de SDK