Gerador de Blueprint de Design de API RESTful

Você é um arquiteto de APIs que projetou APIs usadas por milhões de desenvolvedores em empresas como Stripe, Twilio e GitHub. Suas APIs são conhecidas por serem intuitivas, consistentes e amigáveis para desenvolvedores. Você segue as melhores práticas REST sendo pragmático quanto às necessidades do mundo real. Preciso que você projete uma API completa para o seguinte: ## Requisitos do Projeto Propósito da API: [DESCREVA O QUE A API FAZ] Usuários-Alvo: [QUEM VAI USAR ESTA API] Recursos Principais: [LISTE AS PRINCIPAIS ENTIDADES, ex., Users, Products, Orders] Método de Autenticação: [API KEY / OAuth 2.0 / JWT / etc.] Escala Esperada: [REQUESTS POR SEGUNDO / NÚMERO DE USUÁRIOS] ## Gere um Documento Completo de Design de API: ### 1. VISÃO GERAL DA API - Nome e versão da API (ex., v1) - Recomendação de estrutura de URL base - Content-Type (assume-se JSON, indicar exceções) - Estilo de API (REST, com notas sobre endpoints estilo RPC se necessário) - Recomendação de estratégia de rate limiting ### 2. AUTENTICAÇÃO E AUTORIZAÇÃO Projete o sistema de autenticação: - Detalhes do método de autenticação - Formato e ciclo de vida do token - Estratégia de refresh token (se aplicável) - Modelo de scopes/permissões - Exemplo de headers de autenticação ``` Authorization: Bearer <token> X-API-Key: <api_key> ``` ### 3. DESIGN DE RECURSOS Para cada recurso principal, defina: #### Recurso: [NOME] - Descrição - Relações com outros recursos - Formato do identificador único (UUID, slug, auto-incremento) **Endpoints:** ``` GET /[resources] - List all (with pagination) GET /[resources]/:id - Get single resource POST /[resources] - Create new resource PUT /[resources]/:id - Full update PATCH /[resources]/:id - Partial update DELETE /[resources]/:id - Delete resource ``` **Esquema de Dados:** ```json { "id": "string (uuid)", "created_at": "string (ISO 8601)", "updated_at": "string (ISO 8601)", // ... resource-specific fields } ``` **Tabela de Definição de Campos:** | Campo | Tipo | Obrigatório | Descrição | Restrições | |-------|------|--------------|------------|------------| ### 4. FORMATOS DE REQUEST/RESPONSE **Resposta Padrão de Sucesso:** ```json { "data": { ... }, "meta": { "request_id": "req_abc123", "timestamp": "2024-01-15T10:30:00Z" } } ``` **Resposta de Lista (com paginação):** ```json { "data": [ ... ], "pagination": { "total": 100, "page": 1, "per_page": 20, "total_pages": 5, "next_cursor": "eyJpZCI6MTAwfQ==", "has_more": true }, "meta": { ... } } ``` **Parâmetros de Query para Listas:** - `page` / `cursor` - Paginação - `per_page` / `limit` - Itens por página (máx 100) - `sort` - Campo para ordenação - `order` - asc/desc - `filter[field]` - Filtragem - `include` - Recursos relacionados a incluir - `fields` - Sparse fieldsets (seleção de campos) ### 5. TRATAMENTO DE ERROS **Formato de Resposta de Erro:** ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human readable message", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Email must be a valid email address" } ], "request_id": "req_abc123", "documentation_url": "https://api.example.com/docs/errors#VALIDATION_ERROR" } } ``` **Códigos de Erro Padrão:** | Status HTTP | Código de Erro | Descrição | |-------------|-----------------|-----------| | 400 | VALIDATION_ERROR | Falha na validação da requisição | | 401 | UNAUTHORIZED | Autenticação ausente ou inválida | | 403 | FORBIDDEN | Autenticação válida, mas permissões insuficientes | | 404 | NOT_FOUND | O recurso não existe | | 409 | CONFLICT | Conflito de estado do recurso | | 422 | UNPROCESSABLE | Sintaxe válida, mas erro semântico | | 429 | RATE_LIMITED | Muitas requisições | | 500 | INTERNAL_ERROR | Erro do servidor | ### 6. ESTRATÉGIA DE VERSIONAMENTO - Versionamento por URL: `/v1/resources` - Opção de versionamento por header: `API-Version: 2024-01-15` - Política de depreciação - Modelo de guia de migração ### 7. DESIGN DE PAGINAÇÃO Escolha e documente: - Baseada em offset: `?page=2&per_page=20` - Baseada em cursor: `?cursor=eyJpZCI6MTAwfQ==` - Keyset: `?after_id=100` Inclua prós/contras da abordagem escolhida. ### 8. FILTRAGEM E BUSCA Projete padrões de query: ``` GET /products?filter[category]=electronics GET /products?filter[price][gte]=100&filter[price][lte]=500 GET /products?search=keyword GET /products?status=active,pending ``` ### 9. RATE LIMITING - Níveis de rate limit (por plano/nível de autenticação) - Headers a retornar: - `X-RateLimit-Limit` - `X-RateLimit-Remaining` - `X-RateLimit-Reset` - Header Retry-After no código 429 ### 10. WEBHOOKS (se aplicável) - Tipos de evento - Formato do payload - Verificação de assinatura - Política de retentativas ### 11. ESPECIFICAÇÃO OPENAPI Gere YAML do OpenAPI 3.0 para os endpoints principais: ```yaml openapi: 3.0.0 info: title: [API Name] version: 1.0.0 paths: /[resource]: get: summary: List [resources] # ... complete specification ``` ### 12. CONSIDERAÇÕES SOBRE SDK - Padrões de SDK recomendados - Nomenclatura idiomática para diferentes linguagens - Expectativas de tratamento de erros - Helpers de paginação Torne todos os designs consistentes, seguindo padrões da indústria. Justifique as decisões de design. Inclua exemplos com curl para os endpoints principais.