API do canon
Referência dos contratos HTTP que um projeto recém-gerado pelo dotnet new itlab-fullstack
expõe. A fonte autoritativa é o spec OpenAPI 3.1 commitado no template — também servido
por este site em /openapi/v1.json — e, com a API rodando,
a UI navegável em GET /scalar/v1.
| Seção | Cobre |
|---|---|
| Autenticação | /v1/auth/*, JWKS, fluxos cookie/Bearer/S2S |
| Orders | feature canon /v1/orders/* |
| Operacional | health, OpenAPI, Scalar |
Versionamento
Endpoints de feature são versionados por URL segment (/v1/orders), com header
X-Api-Version: 1.0 como fallback para clientes que não conseguem reescrever URL.
- Quem omite a versão cai na default (
1.0). - Toda resposta carrega
api-supported-versions/api-deprecated-versions. - Endpoints operacionais (
/health) não são versionados.
Erros (Result pattern → HTTP)
Handlers retornam Result/Result<T> com Error tipado; o ToHttpResult() mapeia
ErrorType para status code:
ErrorType | Status |
|---|---|
Validation | 400 Bad Request (com os erros field-level do FluentValidation) |
Unauthorized | 401 / 403 |
NotFound | 404 Not Found |
Conflict | 409 Conflict |
Failure / Problem | 422 / 500 |
Falhas esperadas sempre chegam como Result mapeado — exceptions só para o
inesperado (500).
Rate limiting
Fixed-window global por IP (default 1000 req/60s, configurável). Excedeu →
429 Too Many Requests. Probes de health são isentos.
Autenticação em uma linha
Dois schemes coexistem (detalhes): requests com
Authorization: Bearer … validam JWT contra o JWKS da própria API; sem o header, vale o
cookie de sessão BFF. Endpoints protegidos exigem permissões (Orders.Create etc.)
resolvidas das roles do usuário.