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
Designing with LLM structured outputs
Define esquemas, activa el modo de salida estructurada que documente tu proveedor, valida siempre en servidor y trata los rechazos como eventos de primera clase—fundamental cuando los regex sobre texto libre son demasiado frágiles en producción.
Agentic workflow design
Estructura tareas de agente multi-step con inputs explícitos, outputs, comportamiento de fallback y protocolos de handoff para que los agentes completen workflows complejos fiablemente en lugar de detenerse en el primer blocker. Agentic workflow design aplica disciplina de ingeniería de software a pipelines de agente de IA, tratando cada paso como una función con inputs y outputs tipados.
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.