KIS-TOiR/docs/api-dsl-conventions.md

api.dsl Conventions

Grammar and authoring conventions for domain/*.api.dsl files. See domain/toir.api.dsl as the canonical example.

---

File location and naming

• All api.dsl files live in domain/.
• Naming: <project>.api.dsl (e.g. toir.api.dsl).
• Multiple api.dsl files are allowed but not required.

---

Two top-level block types

An api.dsl file contains two types of top-level blocks:

1. dto — defines the shape of a data transfer object
2. api — declares a group of API endpoints for one resource

---

dto block

dto DTO.<Name> {
  description "Human-readable description";

  attribute <fieldName> {
    description "Field description";
    type <type>;
    is required;          // or: is nullable;
    map <Entity>.<field>; // links to a field in domain/*.api.dsl
  }
}

DTO naming convention

DTO name	Purpose
DTO.<Entity>	Full response shape (GET by id, list items)
DTO.<Entity>Create	Create request body
DTO.<Entity>Update	Update request body (partial — all fields nullable)
DTO.<Entity>ListRequest	Paginated list request (filters + page)
DTO.<Entity>ListResponse	Paginated list response (content + page info)

Types

Same scalar types as the domain DSL: uuid, string, text, integer, decimal, date, boolean, or an enum name from domain/*.api.dsl.

Cross-DTO references: DTO.<Name> or DTO.<Name>[].

Standard pagination types (not entity-specific; treated as well-known): DTO.Filter[], DTO.PageRequest, DTO.PageInfo.

is required vs is nullable

Unlike the domain DSL (where these drive DB constraints), in api.dsl these drive the TypeScript DTO property modifier:

• is required → field!: type in the generated class
• is nullable → field?: type in the generated class
• Neither modifier → treated as optional (field?: type)

map directive

map Entity.field links the DTO attribute to a domain entity field.

Rules:

• The entity and field must exist in domain/*.api.dsl.
• The scalar type must match the domain DSL field type (nullability may differ).
• Omit map only for pagination helper types (DTO.Filter[], DTO.PageRequest, etc.) that have no direct entity field counterpart.

Conflict resolution

If the type declared in a dto attribute conflicts with the domain DSL field type, the domain DSL is correct. Fix the api.dsl.

---

api block

api API.<Name> {
  description "API group description";

  endpoint <endpointName> {
    label "METHOD /path";
    description "Endpoint description";

    // For endpoints with a request body:
    attribute request {
      type DTO.<RequestDto>;
    }

    // For endpoints with a response body:
    attribute response {
      type DTO.<ResponseDto>;
    }

    // For path parameters:
    attribute <paramName> {
      type <type>;
    }
  }
}

api block naming

API.<EntityName> (e.g. API.Equipment, API.RepairOrder)

endpoint label

label "METHOD /path" is the authoritative declaration of HTTP verb and route.

Label pattern	NestJS decorator	Notes
"GET /resource/{id}"	@Get(':id')
"POST /resource"	@Post()	Create
"POST /resource/page"	@Post('page')	Paginated list (body-based filter)
"PUT /resource/{id}"	@Put(':id')	Full or partial update
"DELETE /resource/{id}"	@Delete(':id')

Do not infer HTTP verbs from endpoint names. Always read the label.

Path parameters

Declared as a plain attribute inside the endpoint block (not wrapped in request or response):

attribute id {
  type uuid;
}

Standard 5-endpoint CRUD pattern

Endpoint name	Label	Body
list<Entity>s	"POST /<path>/page"	request: DTO.<Entity>ListRequest, response: DTO.<Entity>ListResponse
get<Entity>	"GET /<path>/{id}"	path param id, response: DTO.<Entity>
create<Entity>	"POST /<path>"	request: DTO.<Entity>Create
update<Entity>	"PUT /<path>/{id}"	path param id, request: DTO.<Entity>Update
delete<Entity>	"DELETE /<path>/{id}"	path param id

---

Constraints

1. Every map Entity.field must resolve to an existing entity + field in domain/*.api.dsl.
2. Types in api.dsl must be compatible with domain DSL field types (same scalar type).
3. api.dsl must not define entities or enums. Those belong in domain/*.api.dsl.
4. An api.dsl may omit domain entity fields from a DTO (e.g. no PK in Create DTO). It must not add fields that don't exist in the domain model.