Skip to content

API Specification Foundation

Purpose

This section defines implementation-level API specification standards for Algosure. These standards will be used later to write actual endpoint contracts, OpenAPI files, test contracts, and client-facing documentation.

This is not an endpoint catalogue. It defines the contract rules that endpoint specifications must follow.

Scope

Area Standard
API specification rules API Specification Standard
OpenAPI contract source OpenAPI Strategy
Response and error shape Request Response Standard
Error identifiers Error Code Catalogue
Authentication and authorization Authentication Authorization Standard
Tenant and organization context Tenant Context Standard
Retry-safe commands Idempotency Standard
Collection reads Pagination Filtering Sorting Standard
API lifecycle API Versioning Standard
Verification API Testing Standard

Architecture Alignment

flowchart TB
    Client[Mobile, Web, AIOS, Integrations]
    API[Domain-Owned API Contract]
    Security[Keycloak, Identity, Authorization]
    Tenant[Tenant and Organization Context]
    Entitlement[Billing Entitlements]
    Module[Spring Boot Modulith Module]
    Service[Owning Application Service]

    Client --> API
    API --> Security
    Security --> Tenant
    Tenant --> Entitlement
    Entitlement --> Module
    Module --> Service

Rules

  • REST-first APIs are the default.
  • OpenAPI becomes the future source of truth after endpoint design is approved.
  • APIs are owned by the Spring Boot Modulith module that owns the Domain.
  • API contracts must not expose aggregates, repositories, internal events, or database tables.
  • Keycloak authenticates callers; Identity owns business authorization decisions.
  • Billing owns entitlement facts used by API access decisions.
  • OrganizationId and tenant context are explicit for organization-scoped APIs.
  • AIOS tool calls use governed internal APIs and are auditable.
  • Integration APIs remain separate from public application APIs and internal APIs.

Non-Goals

This section does not define final endpoint paths, request schemas, response schemas for specific resources, OpenAPI files, generated SDKs, gateway configuration, or Java code.