¿Qué hace api-patterns?
Principios de diseño de API y toma de decisiones. Selección entre REST vs GraphQL vs tRPC, formatos de respuesta, versionado, paginación.
Descripción General
Este skill ayuda a diseñar APIs modernas, escalables y mantenibles. Proporciona criterios de evaluación para decidir entre los patrones de API más comunes y establece guías para aspectos clave como:
- Selección del estilo de API (REST, GraphQL, tRPC)
- Formatos de respuesta (JSON, XML, Protocol Buffers)
- Estrategias de versionado (URL, headers, negociación de contenido)
- Técnicas de paginación (cursor, offset, keyset)
Árbol de Decisión: REST vs GraphQL vs tRPC
| Criterio | REST | GraphQL | tRPC |
|---|---|---|---|
| Simpleza | Alta | Media | Alta |
| Flexibilidad de consultas | Baja | Alta | Alta |
| Tipado | Opcional (OpenAPI) | Fuerte (SDL) | Fuerte (TypeScript) |
| Caché | Nativa (HTTP) | Personalizada | No nativa |
| Over-fetching | Posible | Evitado | Evitado |
| Ecosistema | Maduro | Maduro | Emergente |
Cuándo usar cada uno
- REST: Ideal para APIs públicas, CRUD simples, y cuando se necesita amplio soporte de herramientas.
- GraphQL: Adecuado para aplicaciones con datos complejos y relaciones profundas, o cuando el cliente necesita control granular.
- tRPC: Excelente para monolitos o microservicios en TypeScript, donde se desea tipado completo sin generación de código.
Formatos de Respuesta
- JSON: Estándar de facto, legible, soporte universal.
- XML: Útil en entornos legacy o integraciones con sistemas SOAP.
- Protocol Buffers: Óptimo para alto rendimiento y bajo ancho de banda (ej. microservicios internos).
Versionado de API
- Versión en URL:
GET /api/v1/users(simple, pero rompe URLs). - Versión en headers:
Accept: application/vnd.myapi.v1+json(más RESTful, pero menos intuitivo). - Negociación de contenido: Usar
Acceptpara versionar (flexible, pero complejo).
Recomendación: Usar versionado en URL para APIs públicas, y headers para APIs internas.
Paginación
| Método | Uso | Ventajas | Desventajas |
|---|---|---|---|
| Cursor | GET /items?cursor=abc123 | Eficiente, estable | Complejo de implementar |
| Offset | GET /items?offset=20&limit=10 | Simple | Inconsistente con datos cambiantes |
| Keyset | GET /items?after_id=123 | Rápido, escalable | Requiere orden único |
Recomendación: Usar paginación por cursor para listas grandes y aplicaciones en tiempo real; offset para paneles internos.
Ejemplo de Uso con Agente
Contexto: El usuario necesita decidir qué estilo de API usar para un nuevo backend de comercio electrónico con frontend React y aplicación móvil.
Pasos:
1. Evaluar requisitos: datos de productos, carrito, usuarios.
2. Identificar relaciones: productos con múltiples categorías y variantes.
3. Usar el árbol de decisión: GraphQL es mejor por la flexibilidad de consultas y evitación de over-fetching.
4. Recomendar: GraphQL con Apollo Server en Node.js, versionado por headers, paginación por cursor con `after` y `first`.
Notas Finales
- Este skill no reemplaza el análisis detallado del equipo; ofrece guías basadas en buenas prácticas.
- Los patrones pueden combinarse (ej. REST para autenticación, GraphQL para datos principales).
- Revisa siempre la documentación oficial de cada tecnología para detalles de implementación.