GrydCrud API Reference (V1)

Contrato HTTP oficial dos controllers base:

• CrudController<TEntity, TCreateDto, TUpdateDto, TResultDto, TQueryParameters>
• CrudController<TEntity, TDto>
• CqrsCrudController<TEntity, TCreateDto, TUpdateDto, TResultDto, TQueryParameters>
• CqrsCrudController<TEntity, TDto>

Principios do contrato

• O prefixo de rota e definido no controller derivado (exemplo: /api/v1/users).
• O base controller define apenas sufixo e verbo dos endpoints.
• Sucesso: payload direto (T, PagedResult<T>, vazio em 204).
• Erro: ProblemDetails (application/problem+json).
• Versao da API permanece v1.

Endpoints base por recurso

1) Listagem paginada

GET /

Request (query): TQueryParameters : QueryParameters

Campos base:

• page (default 1)
• pageSize (default 20, max 100)
• sortBy (opcional)
• sortDirection (Ascending | Descending)
• search (opcional)
• includeDeleted (default false)
• campos adicionais de TQueryParameters (quando existirem)

Response:

• 200 OK
• Body: PagedResult<TResultDto>

{
  "items": [],
  "totalCount": 0,
  "pageNumber": 1,
  "pageSize": 20,
  "totalPages": 0,
  "hasNext": false,
  "hasPrevious": false
}

Erros:

• 400 BadRequest (ProblemDetails)

2) Obter por ID

GET /{id:guid}

Request:

• Path: id: Guid

Response:

• 200 OK
• Body: TResultDto

Erros:

• 404 NotFound (ProblemDetails)
• 400 BadRequest (ProblemDetails)

3) Criar

POST /

Request:

• Body: TCreateDto

Response:

• 201 Created
• Header: Location para GetById
• Body: TResultDto

Erros:

• 400 BadRequest (ProblemDetails)

4) Atualizar

PUT /{id:guid}

Request:

• Path: id: Guid
• Body: TUpdateDto

Response:

• 200 OK
• Body: TResultDto

Erros:

• 404 NotFound (ProblemDetails)
• 400 BadRequest (ProblemDetails)

5) Excluir

DELETE /{id:guid}

Request:

• Path: id: Guid

Response:

• 204 NoContent
• Sem body

Erros:

• 404 NotFound (ProblemDetails)
• 400 BadRequest (ProblemDetails)

Formato de erro padrao

Todas as falhas retornam ProblemDetails com campos RFC 7807 e extensoes padrao:

• status
• title
• detail
• type
• instance
• traceId (extension)
• code (extension)
• errors (extension, quando aplicavel)

Exemplo:

{
  "type": "https://gryd.io/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "instance": "/api/v1/users",
  "traceId": "00-...",
  "code": "VALIDATION_ERROR",
  "errors": {
    "email": ["Email is required"]
  }
}

Mapeamento de status por sufixo de code

• *_NOT_FOUND -> 404
• *_ALREADY_EXISTS, *_ALREADY_ASSIGNED, *_CONFLICT -> 409
• *_FORBIDDEN, *_ACCESS_DENIED -> 403
• *_UNAUTHORIZED -> 401
• *_UNPROCESSABLE -> 422
• sem sufixo conhecido -> 400

Variantes de assinatura

Completa

CrudController<TEntity, TCreateDto, TUpdateDto, TResultDto, TQueryParameters>

• DTOs distintos para create/update/result
• query customizada

Simplificada

CrudController<TEntity, TDto>

• mesmo DTO para create/update/result
• usa QueryParameters padrao

CQRS equivalente

CqrsCrudController<...> exposto com o mesmo contrato HTTP acima.

Contratos padrao para cenarios nao CRUD simples

Disponiveis em src/Core/Gryd.API/Contracts/StandardContracts.cs:

• PagedAndSortedRequest
• BulkRequest<TItem>
• OperationResponse<TData>
• BulkOperationResponse
• BulkItemFailure

Esses contratos podem ser usados em endpoints customizados mantendo padrao de request/response e sem quebrar o contrato HTTP V1.

Meta de paginacao para endpoints customizados

Para endpoints customizados de listagem, use OperationResponse<TData> com Meta tipada em QueryMeta:

• Arquivo: src/Core/Gryd.API/Contracts/QueryMeta.cs
• Campos:
  • page, pageSize, totalCount, totalPages
  • hasNext, hasPrevious
  • sortBy, sortDirection

No modulo CRUD, o CustomListController<TRequest, TItem> ja monta esse formato automaticamente.