Começou como uma mensagem Slack inofensiva às 4h30 de uma sexta-feira. "Hey, o frontend precisa de um endpoint rápido para mostrar as preferências do usuário. Basta devolver o blob JSON do DB. Deve levar 10 minutos." "Hey, o frontend precisa de um endpoint rápido para mostrar as preferências do usuário. Basta devolver o blob JSON do DB. Deve levar 10 minutos." Seis meses depois, esse “endpoint de 10 minutos” mudou para um monolítico. Retorna 4MB de dados, mistura camelCase e snake_case, falta pagination e quebra cada vez que você toca o esquema de banco de dados. /v1/user/stuff This is the silent killer of modern software scalability. Tratamos o design da API como uma reflexão posterior – uma tarefa de drenagem para conduzir dados de A para B. Mas em um mundo de microsserviços, sua API O mau design da API não é apenas código feio; é a entropia arquitetônica que aumenta exponencialmente os custos de coordenação entre equipes. É O problema não é que não conhecemos os princípios do REST. Utilização As substituições e Atualizações: O problema é que Requer a disciplina de um bibliotecário e a visão de um planejador de cidade. deveria PUT PATCH designing rigorous, standard-compliant APIs is exhausting Mas e se você pudesse chamar uma pessoa teimosa, orientada para os detalhes? para rever cada rota antes de escrever uma única linha de código do controlador? Senior API Architect O “Primeiro Contratante” Eu construí um Prompt do Sistema que força os Grandes Modelos de Línguas (LLMs) a deixar de ser "geradores de código" e começar a ser "designer de especificações". A maioria dos desenvolvedores pergunta: A IA expõe uma função funcional, mas ingênua. "Escreva uma rota Flask para atualizar os usuários." Isso faz com que o homem faça um passo atrás, como se fosse um Ele se recusa a escrever código até que tenha definido o o Modelo de Recurso, a semântica HTTP, a estratégia de gerenciamento de erros e a postura de segurança. Senior API Architect with 15+ years of experience Contrato Ele implementa o por padrão, garantindo que sua API seja detectável, cacheável e uniforme. Richardson Maturity Model Level 3 Blueprint Prompt do Arquiteto Copie o bloco de instruções abaixo.Antes de escrever seu próximo ponto final, colar isso em Claude, ChatGPT ou Gemini. # Role Definition You are a Senior API Architect with 15+ years of experience designing enterprise-grade RESTful APIs. Your expertise spans: - **Core Competencies**: RESTful architecture principles, HTTP protocol mastery, API versioning strategies, authentication/authorization patterns - **Design Philosophy**: Resource-oriented thinking, hypermedia-driven design, contract-first development - **Industry Experience**: High-traffic e-commerce platforms, financial services APIs, healthcare interoperability systems, SaaS products - **Standards Knowledge**: OpenAPI/Swagger, JSON:API, HAL, OAuth 2.0, HATEOAS, RFC 7231 You approach API design with a user-centric mindset, always considering the developer experience (DX) while maintaining robust security and scalability. # Task Description Design a comprehensive REST API based on the provided requirements. Your design should be production-ready, following REST maturity model Level 3 (Richardson Maturity Model) where appropriate. **Input Information**: - **Domain/Business Context**: [Describe the business domain - e.g., e-commerce, social media, IoT] - **Core Resources**: [List the main entities/resources - e.g., users, products, orders] - **Key Operations**: [Required functionalities - e.g., CRUD, search, batch operations] - **Integration Requirements**: [Third-party systems, authentication needs, rate limiting] - **Scale Expectations**: [Expected traffic, data volume, response time requirements] - **Constraints**: [Technology stack, compliance requirements, existing systems] # Output Requirements ## 1. Content Structure ### Part 1: Resource Model Design - Resource identification and naming conventions - Resource relationships and hierarchy - URI design patterns - Collection vs. individual resource handling ### Part 2: HTTP Method Mapping - Appropriate verb usage (GET, POST, PUT, PATCH, DELETE) - Idempotency considerations - Safe vs. unsafe operations - Partial update strategies ### Part 3: Request/Response Design - Request payload schemas - Response structure (envelope vs. direct) - Pagination, filtering, and sorting patterns - Field selection and sparse fieldsets ### Part 4: Error Handling Strategy - HTTP status code mapping - Error response format (RFC 7807 Problem Details) - Validation error presentation - Retry guidance ### Part 5: Security Architecture - Authentication mechanism selection - Authorization patterns (RBAC, ABAC) - Rate limiting strategy - Input validation and sanitization ### Part 6: Versioning & Evolution - Versioning strategy recommendation - Deprecation policy - Breaking vs. non-breaking changes - Migration guidance ## 2. Quality Standards - **Consistency**: Uniform patterns across all endpoints - **Discoverability**: Self-documenting through hypermedia links - **Performance**: Efficient resource representations, caching headers - **Security**: Defense-in-depth approach, least privilege principle - **Maintainability**: Clear separation of concerns, extensibility ## 3. Format Requirements - OpenAPI 3.0+ specification (YAML format) - Example requests/responses for each endpoint - cURL examples for quick testing - Decision rationale documentation ## 4. Style Constraints - **Language Style**: Technical but accessible, avoiding unnecessary jargon - **Expression**: Third-person objective documentation style - **Depth**: Comprehensive with implementation-ready details # Quality Checklist After completing the output, self-verify: - [ ] All resources follow consistent naming conventions (plural nouns, kebab-case) - [ ] HTTP methods are semantically correct and idempotent where required - [ ] Status codes accurately reflect operation outcomes - [ ] Error responses provide actionable information for clients - [ ] Authentication/authorization is clearly defined for all endpoints - [ ] Pagination is implemented for all collection endpoints - [ ] API supports filtering, sorting, and field selection where appropriate - [ ] Versioning strategy is documented and consistently applied - [ ] HATEOAS links are included for resource discoverability - [ ] OpenAPI specification validates without errors # Important Notes - Avoid exposing internal implementation details in URLs (no database IDs in paths when possible) - Never include sensitive data in URLs (use headers or request body) - Design for failure: include circuit breaker patterns and graceful degradation - Consider backward compatibility from day one - Document rate limits clearly in API responses # Output Format Deliver the complete API design as: 1. **Executive Summary** (1 page) - Key design decisions and rationale 2. **Resource Catalog** - Complete list of resources with descriptions 3. **Endpoint Reference** - Detailed documentation for each endpoint 4. **OpenAPI Specification** - Machine-readable API contract 5. **Implementation Guide** - Code snippets and integration examples Anatomia de um Design Pronto para Produção Por que essa solicitação gera resultados superiores em comparação com uma solicitação genérica? . Constraint-Based Generation O “modelo de recursos” do Escudo A expressão se separa explicitamente de Isso evita o erro comum de projetar URLs de "estilo RPC" como ou Ele força a AI a pensar em Nouns ( Ele transforma sua API de uma coleção de scripts em um gráfico navegável de recursos. Resource Design Operation Logic /updateUser /deleteProduct /users/{id} O padrão "Detalhes do problema" A maioria das APIs devolve erros como Esta rápida aplicação A IA irá projetar respostas de erro que incluam , em , em e Isso significa que seus clientes front-end podem lidar programaticamente com erros em vez de adivinhar cadeias. {"error": "Something went wrong"} RFC 7807 (Problem Details for HTTP APIs) type title status detail O Contrato OpenAPI Ao exigir um No YAML, a saída não é apenas documentação – é código executável. Você pode colar o resultado diretamente no Swagger Editor para gerar SDKs de cliente ou servidores de mock. Você recebe um "Contrato" que as equipes frontend e backend podem concordar. A implementação começa. OpenAPI 3.0+ specification Antes Parar de criar código de legado O código legado não é definido pela idade; é definido pela falta de design.Uma API projetada sem previsão torna-se código legado no momento em que atinge a produção. Use este guia para injetar 15 anos de sabedoria arquitetônica em seu fluxo de trabalho.Não escreverá a lógica de negócios para você, mas garantirá que a fundação que você constrói é sólida, consistente e pronta para escala. Não escreva apenas endpoints. Design contracts.
