API Specification Standard

Purpose

The API Specification Standard defines the minimum information every future Algosure API contract must contain.

Required Specification Fields

Field	Requirement
Domain owner	Owning Spring Boot Modulith module and Domain.
API category	Public application, internal, AIOS tool, or integration API.
Resource responsibility	Business resource or workflow responsibility.
Command or query	Whether the API changes state or reads state.
Authentication	Keycloak token, service account, API key, or integration credential model.
Authorization	Identity permission, role, policy, ownership, approval, and workflow checks.
Entitlement	Billing entitlement, plan, usage, feature, or limit requirement.
Tenant context	Required TenantId and OrganizationId behavior.
Request model	Fields, validation rules, idempotency, and correlation metadata.
Response model	Standard envelope, payload, metadata, and links.
Error model	Standard error response and error codes.
Events	Events published or consumed by the operation where applicable.
Audit	Audit requirement for sensitive reads and material commands.
Testing	Contract, security, tenant, and idempotency test expectations.

Contract Boundary

flowchart LR
    Spec[API Specification]
    Controller[api.rest]
    DTO[api.dto]
    Mapper[api.mapper]
    App[application.service]
    Domain[domain.model]

    Spec --> Controller
    Controller --> DTO
    DTO --> Mapper
    Mapper --> App
    App --> Domain

Rules

• API specifications use domain language, not table names or UI component names.
• API DTOs are contracts and must not expose internal aggregates.
• State-changing APIs call owning application services.
• Query APIs return read models, summaries, projections, or view models owned by the Domain.
• Cross-module references use stable identifiers and do not imply ownership transfer.
• Sensitive endpoints must document audit and approval behavior.

Review Checklist

• Does the API preserve Domain ownership?
• Is the owning Modulith module explicit?
• Are tenant, organization, actor, correlation, and entitlement contexts clear?
• Are validation and error cases specified?
• Is idempotency required for retryable unsafe commands?
• Are AIOS and integration consumers separated from public application consumers?