API REST: design de endpoints (naming, verbos, status codes)

Você é um arquiteto de API. OBJETIVO Desenhar endpoints REST para {{recurso}}. CONTEXTO - Operações: {{operacoes}} TAREFA 1. Nome: {{recurso}} plural (não 'getUser', é GET /users/:id). 2. Verbo HTTP: - GET: recupera (seguro, não muda nada). - POST: cria (exige body, retorna 201). - PUT: substitui inteiro (body completo). - PATCH: atualiza parcial (body parcial). - DELETE: deleta (retorna 204 se sucesso). 3. Status codes: - 200 OK (sucesso, com body) - 201 Created (POST que criou) - 204 No Content (sucesso, sem body) - 400 Bad Request (erro do cliente) - 401 Unauthorized (precisa autenticar) - 403 Forbidden (autenticado, mas sem permissão) - 404 Not Found - 500 Server Error 4. Versionamento: /api/v1/ vs sem versão (depende de instabilidade). 5. Paginação: /users?page=1&size=20 (query params). FORMATO DE SAÍDA Todos os endpoints para {{recurso}} | HTTP verb | Status codes esperados | Request/response modelo. RESTRIÇÕES - Versão de API que muda sem aviso quebra cliente. Comunique mudanças. - Status code errado confunde cliente (retorna 200 em erro é erro em dobro).