DomainTemplate API Reference

The API manages DomainTemplate business object. Its singular base path is /api/v1/domaintemplate. Swagger UI is published at /swagger-ui.html.

All business endpoints require JWT authentication. Obtain a token with POST /api/v1/auth/login, then send it as Authorization: Bearer <token>. The forced administrator account is configured with APP_ADMIN_USERNAME and APP_ADMIN_PASSWORD at API startup.

Resource Schema

Field	JSON type	Required	Rules
id	number	Response only	Server-generated Java Long.
code	string	Yes	Unique and immutable.
label	string	Yes	Non-blank and mutable.
description	string or null	No	Mutable.
createdDate	string	Response only	Server-owned Instant in ISO-8601 format.
lastModifiedDate	string	Response only	Server-owned Instant in ISO-8601 format.

Endpoints

Authentication and Administration

Method	Path	Description
POST	/api/v1/auth/login	Exchange username/password for a JWT.
GET	/api/v1/auth/me	Read the authenticated user.
GET	/api/v1/auth/users	List users. Requires ADMIN.
POST	/api/v1/auth/users	Create a user with a BCrypt-stored password. Requires ADMIN.
GET	/api/v1/auth/users/{id}	Read a user. Requires ADMIN.
PUT	/api/v1/auth/users/{id}	Update username, enabled flag, roles, and optionally password. Requires ADMIN.
DELETE	/api/v1/auth/users/{id}	Delete a user. Requires ADMIN.
GET	/api/v1/auth/roles	List roles. Requires ADMIN.
POST	/api/v1/auth/roles	Create a role. Requires ADMIN.
GET	/api/v1/auth/roles/{id}	Read a role. Requires ADMIN.
PUT	/api/v1/auth/roles/{id}	Update a role label. Requires ADMIN.
DELETE	/api/v1/auth/roles/{id}	Delete a non-system role. Requires ADMIN.

The ADMIN and USER roles are seeded at first startup. User responses never include passwords or password hashes.

DomainTemplate

Method	Path	Description
GET	/api/v1/domaintemplate	List all objects, ordered by code.
GET	/api/v1/domaintemplate/{id}	Read one object by server ID.
POST	/api/v1/domaintemplate	Create an object.
PUT	/api/v1/domaintemplate/{id}	Update its mutable fields.
DELETE	/api/v1/domaintemplate/{id}	Delete one object.
POST	/api/v1/domaintemplate/seed	Upsert an array by code.
POST	/api/v1/domaintemplate/import.json	Import and upsert a JSON array by code.
POST	/api/v1/domaintemplate/import.csv	Import and upsert CSV rows by code.
GET	/api/v1/domaintemplate/export.json	Export all objects as JSON.
GET	/api/v1/domaintemplate/export.csv	Export all objects as CSV.

Create

POST /api/v1/domaintemplate accepts only business fields:

{
  "code": "CUSTOMER",
  "label": "Customer",
  "description": "Customer master data"
}

The response is 201 Created, includes the complete resource, and sets Location to /api/v1/domaintemplate/{id}. A duplicate code returns 409 Conflict. Blank required fields return 400 Bad Request.

Read

GET /api/v1/domaintemplate returns a JSON array. GET /api/v1/domaintemplate/{id} returns one object or 404 Not Found.

Update

PUT /api/v1/domaintemplate/{id} accepts the mutable fields only:

{
  "label": "Customer record",
  "description": null
}

The server preserves id, code, and createdDate, and replaces lastModifiedDate. The response is 200 OK, or 404 Not Found for an unknown ID.

Delete

DELETE /api/v1/domaintemplate/{id} returns 204 No Content, or 404 Not Found for an unknown ID.

Seed and Import

Seed and both import formats use upsert semantics keyed by code: a missing code creates an object and an existing code updates label and description. Client-supplied id, createdDate, and lastModifiedDate values are ignored. The server keeps ownership of identifiers and timestamps.

POST /api/v1/domaintemplate/seed and POST /api/v1/domaintemplate/import.json accept an array. A minimal document is:

[
  {
    "code": "CUSTOMER",
    "label": "Customer",
    "description": null
  }
]

Both return 201 Created with the stored resources.

Import and Export Formats

JSON export returns the complete resource schema. The same exported JSON can be imported: server-owned fields are accepted only as transport data and ignored during the upsert.

[
  {
    "id": 42,
    "code": "CUSTOMER",
    "label": "Customer",
    "description": "Customer master data",
    "createdDate": "2026-08-30T17:00:00Z",
    "lastModifiedDate": "2026-08-30T17:00:00Z"
  }
]

CSV import and export use this header:

id,code,label,description,createdDate,lastModifiedDate

All six columns are required in the CSV header so an export can round-trip. On import, id, createdDate, and lastModifiedDate are ignored; empty description becomes null.

id,code,label,description,createdDate,lastModifiedDate
42,CUSTOMER,Customer,Customer master data,2026-08-30T17:00:00Z,2026-08-30T17:00:00Z

Response

{
  "id": 42,
  "code": "CUSTOMER",
  "label": "Customer",
  "description": "Customer master data",
  "createdDate": "2026-08-30T17:00:00Z",
  "lastModifiedDate": "2026-08-30T17:05:00Z"
}

Clients

The java-client, react-client, and dart-client modules provide typed Java, TypeScript, and Dart access to CRUD, seed, import, and export operations. Construct each client with the service origin; the client appends /api/v1/domaintemplate.

The react-client also generates RTK Query endpoints and exports an AuthClient for login, current-user lookup, and user and role administration under /api/v1/auth.