restful-api
Installation
SKILL.md
Diretrizes para APIs REST/HTTP
Skill transversal e agnostica a linguagem/framework. Aplica-se igualmente a servicos em .NET, Java/Spring, Node.js, Python, Go, Rust, etc. As regras aqui descritas tratam do contrato HTTP/OpenAPI, não da implementacao especifica.
1. Mapeamento de Endpoints
Utilize o estilo idiomatico do framework HTTP escolhido (ex.: Controllers, Minimal APIs, Route handlers, Resource classes, Decorators). Mantenha consistencia interna ao servico: nao misture estilos no mesmo modulo sem motivo. O que importa, do ponto de vista do contrato, e que o endpoint resultante atenda as convencoes descritas a seguir.
2. Padroes de Roteamento e Nomenclatura
2.1. Estrutura de URLs
- Utilize o padrao REST para consultas, mantendo o nome dos recursos em ingles e no plural
- Permita a navegabilidade em recursos aninhados
- Exemplo:
/playlists/{playlistId}/videosou/customers/{customerId}/invoices
- Exemplo:
2.2. Convencao de Nomenclatura
- Para as URLs dos recursos, prefira o padrao kebab-case para melhor legibilidade
- Exemplo:
/scheduled-events
- Exemplo:
- Garanta a convencao no roteamento da framework escolhida (ex.: configurar lower-case routes, kebab-case transformers ou simplesmente declarar os paths nesse formato)