API Principles¶
Executive Summary¶
API Principles defines the rules that guide Algosure API design. APIs must be domain-owned, REST-first, tenant-aware, secure, auditable, mobile-first, and compatible with the Spring Boot Modulith.
Why This Exists¶
APIs are the contract surface between Algosure experiences, AIOS, integrations, and backend Domains. Principles prevent APIs from becoming screen-specific shortcuts, generic technical endpoints, or ownership leaks.
Owner¶
The owner is the Chief Product Officer and Enterprise Architect.
Business Value¶
Clear API principles improve client consistency, reduce rework, and make security and ownership easier to review.
Principles¶
| Principle | Meaning |
|---|---|
| REST-first | REST is the default API style unless an architecture decision justifies another style. |
| Future GraphQL only if justified | GraphQL may be considered later for complex read composition, but only after security, caching, authorization, and operational review. |
| Domain-owned boundaries | Each API belongs to the Domain that owns the business language and source facts. |
| Command/query separation | APIs distinguish command responsibilities from query responsibilities even when both are REST resources. |
| Mobile-first | APIs must support efficient mobile workflows, predictable payloads, network constraints, pagination, and explicit errors. |
| Web app support | APIs must also support richer web workspaces without exposing internal aggregates. |
| Secure by design | Authentication, authorization, permissions, roles, entitlements, tenant context, and audit are part of API design. |
| Multi-tenant by design | Tenant and organization context must be explicit and verified before material work. |
| Contract-first future | OpenAPI should become the formal contract source when endpoint design is approved. |
| Integration separation | Internal, public application, and integration APIs must remain distinct. |
API Design Guardrails¶
| Guardrail | Requirement |
|---|---|
| Do not expose internal aggregates | API contracts are stable representations, not internal domain object dumps. |
| Do not bypass application services | APIs call owning application services, not repositories or internal aggregates directly. |
| Do not encode workflow shortcuts | Workflow state changes must go through owning Domain and workflow rules. |
| Do not duplicate Domain ownership | API convenience must not cause another module to own source facts. |
| Do not weaken authorization for convenience | Client experience requirements do not override tenant, role, permission, entitlement, and approval checks. |
Non-Implementation Boundary¶
This document does not define endpoint naming, payload schemas, status code mappings, client SDKs, or OpenAPI file structure.