Da forma a superficies de API REST o RPC con modelado consistente de recursos, respuestas de error predecibles, endpoints de lista paginados y una política de deprecación explícita antes de que la implementación te encasille en contratos costosos de cambiar. Un buen diseño de API previene breakage de clientes, reduce carga de soporte y hace las adiciones de funcionalidades menos disruptivas.
Casos de uso
- Diseñando un nuevo microservicio greenfield que será consumido por múltiples clientes internos o externos
- Preparando un SDK público donde la estabilidad de API tiene implicaciones legales o de negocio
- Planificando un cambio breaking a una API existente y necesitando comunicar el path de migración a los clientes
- Evaluando si usar REST, gRPC o GraphQL para un nuevo servicio y necesitando documentar los tradeoffs
- Añadiendo un nuevo campo a un response existente y necesitando decidir si es aditivo o un cambio breaking
Funciones principales
- Modela los recursos core y sus relaciones antes de definir endpoints: usa un diagrama de entidad simple para validar que el modelo de recursos es intuitivo para los clientes
- Define el contrato de respuesta de error con códigos de error específicos, mensajes legibles por humanos y campos legibles por máquina para que los clientes manejen errores programáticamente
- Diseña contratos de paginación y filtering para endpoints de lista, especificando semántica de cursor versus offset y tamaños máximos de página
- Documenta la estrategia de versionamiento: cómo los clientes especifican la versión de API, cómo se anuncian los cambios breaking y el timeline de sunset para versiones deprecadas
- Escribe una guía corta de migración de cliente para cualquier cambio no obvio antes de implementar el servidor, para que el contrato sea validado desde la perspectiva del consumidor
Relacionados
Relacionados
3 Entradas indexadas
Codebase indexing
Construye y mantiene índices semánticos de un codebase para que asistentes de codificación de IA puedan retrieve contexto relevante: relaciones de archivos, uso de símbolos, decisiones históricas sin re-parsear el codebase completo en cada query. Codebase indexing es esencial para codebases grandes donde límites de context window previenen alimentar el codebase completo al modelo.
Contract testing
Bloquea expectativas de API entre servicios usando consumer-driven contracts para que cuando un equipo cambia su implementación, falla en CI en lugar de durante un deployment de producción Coordinado. Contract testing previene el patrón común de fallo de integración donde ambos lados de una API parecen trabajar en aislamiento pero rompen cuando se conectan en producción.
Executing implementation plans
Ejecuta un plan de implementación pre-escrito en orden disciplinado, deteniéndose en puntos de control definidos para verificar supuestos antes de avanzar. Esta habilidad previene el patrón común de desviarse del plan silenciosamente cuando la realidad prueba que está equivocado, y crea oportunidades naturales de corregir el rumbo antes de que errores pequeños se compounding en rework grande.