Microservices Checklist

Use the following checklist when designing, implementing, and maintaining microservices within DIT.
This checklist is intended for internal use by DIT software developers and defines the minimum standards a microservice must meet before being considered production-ready.

ID	Name	Description
SMR-1	Authentication	All internal microservice-to-microservice calls must include the following HTTP headers: • X-Auth-User • X-Auth-Signature The value of X-Auth-Signature must be a cryptographic signature validated using the assigned public key. Requests without valid signatures must be rejected.
SMR-2	Database per Service Pattern	Each microservice must have its own independent database. Databases must never be shared across services. This ensures autonomy, avoids coupling, and prevents cross-service side effects.
SMR-3	Events: Use Cloud Native Events	All published messages must follow the Cloud Native Events (CNE) envelope format. The data field inside the event must use JSON:API conventions (see SMR-9).
SMR-4	Events: Idempotent Consumers	Consumers must be fully idempotent. Each message must be processed exactly once from the application’s perspective by using the event ID to prevent duplicate processing.
SMR-5	Events: Transactional Outbox	Events that reflect a change to a resource must be published using the Transactional Outbox Pattern, ensuring that database state change and event publication occur atomically.
SMR-6	Events: Polling Publisher Pattern	A background worker must periodically poll the outbox table for unpublished events and publish them to the message broker. This ensures reliability and resilience in event delivery.
SMR-7	Events: Single Exchange, Multiple Routing Keys	For RabbitMQ-based systems, use a single exchange per service and differentiate event types using routing keys. This ensures clean routing and reduces complexity.
SMR-8	Events: Follow Naming Conventions	All routing keys and queues must follow the naming conventions defined in Annex 1.1 and Annex 1.2. Consistent naming supports predictable routing and easier debugging.
SMR-9	REST: Adopt JSON:API Specification	REST responses must fully comply with the JSON:API specification, including structure, naming, and envelope format.
SMR-10	REST: JSON:API Pagination Extension	All paginated responses must follow the pagination format shown in Annex 2, extending the JSON:API meta object.
SMR-11	REST: JSON:API Request Extension	All REST requests that include bodies must wrap payloads inside the JSON:API data object (see Annex 3).
SMR-12	REST: Async Request-Reply Pattern	For computationally intensive operations or workflows spanning multiple services, use the Asynchronous Request-Reply Pattern (see Annex 4). The initial HTTP response must return 202 ACCEPTED.
SMR-13	REST: Use Camel Case for JSON:API Member Names	All JSON:API member names (attributes, relationships, etc.) must use camelCase.
SMR-14	REST: Use Idempotency Key	All POST, PATCH, and DELETE requests must require an Idempotency-Key header. Requests with the same key must be processed only once.
SMR-15	REST: Use kebab-case for Endpoint Names	All REST endpoint paths must use kebab-case (e.g., /user-profiles, /payment-methods).
SMR-16	Use OpenAPI for REST Documentation	All REST endpoints must be documented using OpenAPI ≥ 3.0. The documentation must be stored alongside the codebase.
SMR-17	Use AsyncAPI for Events Documentation	All published and consumed events must be documented using AsyncAPI ≥ 2.0, ensuring full visibility into event-driven architecture.
SMR-18	Pagination Starts at Page 1	Pagination must start at page = 1, where page 1 corresponds to offset 0. Zero-based page numbering is not permitted.

Annexes

Annex 1 — Naming Conventions

1.1 Routing Key Format

Use the following naming structure for routing keys:

[api-name]-api.[resource-name-plural].[operation-past-tense]

Example:

users-api.users.created

1.2 Queue Name Format

Format when subscribing to another service’s events:

[consumer-api-name]-api.[routing-key-of-publisher]

Example:

orders-api.users-api.users.created

---

Annex 2 — JSON:API Pagination Extension

{
  "meta": {
    "pagination": {
      "totalPages": "integer",
      "count": "integer",
      "rowsPerPage": "integer",
      "page": "integer"
    }
  }
}

---

Annex 3 — JSON:API Request Wrapper

{
  "data": { ...request_payload }
}

---

Annex 4 — Asynchronous Request Response Format

{
  "data": {
    "id": "string",
    "type": "async_request_responses",
    "attributes": {
      "retryAt": "string(datetime)",
      "location": "string"
    }
  }
}