REST conventions

Patterns used by ethica-api (NestJS). Keep examples sanitized (fake IDs, no real PII).

Base URL and format

All HTTP routes are served under the global prefix /api (e.g. GET /api/...).
Request and response bodies are JSON unless the endpoint explicitly returns a file or stream.
Incoming DTOs are validated with class-validator / class-transformer via Nest’s ValidationPipe (whitelist, transform enabled). Unknown properties may be stripped from input depending on configuration.

Success responses

Shape varies by endpoint; prefer explicit DTOs in controllers. Many routes return JSON objects with domain fields as defined in the module.

Error responses

The global HttpExceptionFilter normalizes errors to a single JSON envelope:

{
  "status": "error",
  "error": {
    "message": "Human-readable message"
  }
}

When validation or custom logic supplies structured errors, an errors field may appear inside error:

{
  "status": "error",
  "error": {
    "message": "Bad Request",
    "errors": {}
  }
}

Use the HTTP status code on the response (4xx for client issues, 5xx for server issues). Prefer Nest’s HttpException subclasses so status and body stay consistent.

Pagination and filtering

Many list endpoints use page and limit as query parameters (strings in the query, parsed to numbers in services):

Defaults are module-specific (e.g. page defaults to 1; limit often 10–20, with upper caps such as 100 on some routes).
Responses usually include a pagination (or equivalent) object with total, totalPages, and page/limit fields—exact field names vary by controller (currentPage / perPage vs page / limit, etc.).

Additional filters are per resource (e.g. status on investments, isResolved / date ranges on error logs). Treat each controller’s @Query() parameters and service return types as the contract until a published OpenAPI spec exists.

Idempotency