aw-spec-cli 0.1.9 → 0.1.11

package/assets/guardrails/technology/java-spring/api-versioning.md

@@ -0,0 +1,782 @@
+# API Versioning Governance
+
+> Common technology guardrail for API versioning in AppWeaver Java/Spring applications.
+>
+> Technology-specific and domain-agnostic. This document governs external API contract evolution and compatibility. It does not define domain-specific API behavior.
+
+---
+
+## 1. Purpose
+
+This document defines the API versioning standards for AppWeaver Java applications.
+
+API versioning MUST provide stable and predictable contracts for API consumers while allowing applications to evolve without unnecessarily breaking existing clients.
+
+API versioning is an external API boundary concern.
+
+API-version-specific concerns MUST remain outside the domain model.
+
+API versioning MUST NOT introduce API-version-specific dependencies into:
+
+* domain entities;
+* value objects;
+* domain services;
+* domain events;
+* domain ports;
+
+unless explicitly required by an approved architectural or domain rule.
+
+---
+
+## 2. Scope
+
+These rules apply when an AppWeaver Java application exposes versioned external REST APIs.
+
+The rules govern:
+
+* REST API versioning;
+* inbound web adapters;
+* API request and response contracts;
+* API compatibility and evolution;
+* API deprecation and retirement;
+* OpenAPI documentation, when OpenAPI is used;
+* API versioning-related testing;
+* AI-generated API implementations.
+
+This document does not define:
+
+* domain-specific API behavior;
+* business rules;
+* authorization implementation;
+* exception-handling implementation;
+* Problem Details structure;
+* result-mapping implementation.
+
+Those concerns MUST follow their respective applicable AppWeaver technology guardrails.
+
+---
+
+## 3. Architecture Boundary
+
+The application follows the predefined AppWeaver Java foundation and its Modular Monolith and Hexagonal Architecture principles.
+
+The mandatory production Java source root is:
+
+`backend/src/main/java/io/appweaver/`
+
+The approved top-level architectural packages are:
+
+```text
+backend/src/main/java/io/appweaver/
+├── adapter/
+├── application/
+├── domain/
+└── infrastructure/
+```
+
+API versioning is primarily an inbound API adapter concern.
+
+API-version-specific controllers, request contracts, response contracts, and HTTP mapping logic MUST be placed within the appropriate subpackages of the established AppWeaver foundation structure.
+
+AI agents MUST NOT create a new top-level package directly under:
+
+`io.appweaver`
+
+AI agents MUST NOT introduce alternative architectural structures such as:
+
+* `features`;
+* `feature`;
+* `vertical-slice`;
+* `controller` as a top-level architectural package;
+* `service` as a top-level architectural package;
+* `repository` as a top-level architectural package;
+* or any other competing top-level architecture.
+
+The exact subpackage organization MUST follow the active Java foundation and existing repository conventions.
+
+---
+
+## 4. API Versioning Principles
+
+### 4.1 Explicit Versioning
+
+Public REST APIs SHOULD use an explicit and predictable versioning strategy.
+
+The default AppWeaver strategy is URI-based major versioning.
+
+Recommended format:
+
+```text
+/api/v{major}/{resource}
+```
+
+Examples:
+
+```text
+/api/v1/projects
+/api/v1/projects/{projectId}
+
+/api/v2/projects
+/api/v2/projects/{projectId}
+```
+
+The selected API version MUST be externally identifiable and form part of the API contract.
+
+A project MAY use another approved versioning strategy only when explicitly defined by the project's architecture or API standards.
+
+AI agents MUST NOT introduce a different versioning strategy into an existing application without explicit approval.
+
+---
+
+### 4.2 Version Stability
+
+Once an API version is released for consumer use, incompatible breaking changes MUST NOT be introduced into that version.
+
+Breaking changes SHOULD be introduced through a new API version unless an approved compatibility strategy exists.
+
+Existing API consumers MUST NOT be broken by routine implementation changes.
+
+---
+
+### 4.3 Version Independence
+
+API versions represent external contracts.
+
+API version identifiers MUST remain at the external API boundary.
+
+The domain model MUST remain independent of:
+
+* URI versions;
+* HTTP headers used for versioning;
+* API-specific request structures;
+* API-specific response structures;
+* OpenAPI-specific version representations.
+
+Different external API versions MAY map to the same application use case and domain behavior when their business semantics are equivalent.
+
+A new API version MUST NOT automatically result in duplicated application or domain logic.
+
+---
+
+## 5. Versioning Strategy
+
+### 5.1 Default Strategy
+
+The default AppWeaver API versioning strategy is URI-based major versioning.
+
+Format:
+
+```text
+/api/v{major}/{resource}
+```
+
+Examples:
+
+```text
+/api/v1/projects
+/api/v1/projects/{projectId}
+```
+
+A subsequent breaking version may use:
+
+```text
+/api/v2/projects
+/api/v2/projects/{projectId}
+```
+
+Version identifiers SHOULD use major versions only:
+
+```text
+/api/v1
+/api/v2
+```
+
+The following patterns SHOULD NOT be introduced unless explicitly required by the approved API standard:
+
+```text
+/api/v1.0
+/api/v1.2
+/api/v1.2.3
+
+/api/project-v1
+/api/project/version1
+/api/v1Project
+```
+
+---
+
+### 5.2 Breaking Changes
+
+A new API version SHOULD be introduced when an externally visible change breaks compatibility with existing consumers.
+
+Potentially breaking changes include:
+
+* removing an endpoint;
+* renaming an endpoint;
+* changing an HTTP method;
+* changing HTTP method semantics;
+* removing a request property;
+* removing a response property;
+* renaming a property;
+* changing a property type;
+* changing the meaning of an existing property;
+* making an optional field required incompatibly;
+* changing required request fields incompatibly;
+* changing authentication or authorization requirements incompatibly;
+* changing error contract semantics incompatibly;
+* changing response semantics in a way that breaks consumers.
+
+Compatibility MUST be evaluated based on the published API contract rather than internal implementation changes.
+
+---
+
+### 5.3 Non-Breaking Changes
+
+The following changes MAY remain within the existing API version when backward compatibility is preserved:
+
+* adding a new endpoint;
+* adding an optional request property;
+* adding an optional query parameter;
+* adding a response property when client compatibility is preserved;
+* adding new documented error conditions;
+* improving implementation;
+* improving documentation;
+* internal refactoring that does not alter the published API contract.
+
+An API version MUST NOT be changed merely because:
+
+* internal implementation changed;
+* persistence implementation changed;
+* domain implementation changed;
+* infrastructure changed;
+* a dependency was upgraded;
+* internal refactoring occurred.
+
+---
+
+## 6. URL and Resource Conventions
+
+API URLs MUST follow a consistent structure.
+
+Recommended format:
+
+```text
+/api/v{major}/{resource}
+```
+
+Examples:
+
+```text
+/api/v1/projects
+
+/api/v1/projects/{projectId}
+
+/api/v1/projects/{projectId}/documents
+```
+
+Resource names SHOULD:
+
+* represent stable API concepts;
+* use meaningful nouns;
+* remain consistent across the API;
+* avoid leaking persistence implementation details.
+
+Version changes MUST NOT be used to compensate for inconsistent resource naming or poor API design.
+
+---
+
+## 7. API Contracts
+
+API request and response models MUST be explicit boundary contracts.
+
+Domain entities MUST NOT be exposed directly through REST APIs.
+
+Persistence entities MUST NOT be exposed directly through REST APIs.
+
+API contracts SHOULD use immutable Java representations where appropriate.
+
+Java records MAY be used when appropriate.
+
+Example:
+
+```java
+public record CreateProjectRequest(
+        String name,
+        String description
+) {
+}
+```
+
+A response contract may be represented separately:
+
+```java
+public record ProjectResponse(
+        String projectId,
+        String name,
+        String status
+) {
+}
+```
+
+API contracts MUST remain independent from persistence implementation details.
+
+---
+
+## 8. API Version-Specific Contracts
+
+Different API versions MAY expose different request and response contracts.
+
+For example:
+
+```text
+/api/v1/projects
+        ↓
+CreateProjectV1Request
+        ↓
+Application Use Case
+
+/api/v2/projects
+        ↓
+CreateProjectV2Request
+        ↓
+Application Use Case
+```
+
+When business behavior is equivalent, multiple API versions SHOULD reuse the same application capability.
+
+AI agents MUST NOT duplicate application or domain logic solely because the external API version differs.
+
+Separate application behavior MAY be introduced when the API versions represent genuinely different application semantics.
+
+---
+
+## 9. API Mapping and Application Flow
+
+Mapping between external API contracts and application contracts MUST be explicit.
+
+The recommended architectural flow is:
+
+```text
+HTTP Request
+    ↓
+Inbound Adapter
+    ↓
+API Request Contract
+    ↓
+Application Port / Use Case
+    ↓
+Domain
+    ↓
+Application Result
+    ↓
+API Response Mapping
+    ↓
+HTTP Response
+```
+
+The exact result and HTTP response mapping behavior MUST follow the applicable:
+
+`result_mapping.md`
+
+API request and response mapping MUST NOT expose persistence entities directly.
+
+API-version-specific mapping MUST remain outside the domain model.
+
+---
+
+## 10. Spring Boot and Spring MVC
+
+Spring Boot and Spring MVC MAY be used to implement versioned REST APIs.
+
+Spring-specific concerns MUST remain within the appropriate adapter or infrastructure boundaries defined by the AppWeaver Java foundation.
+
+Controllers act as inbound adapters.
+
+Controllers MUST:
+
+* receive and process HTTP requests;
+* perform applicable boundary validation;
+* map requests to application inputs;
+* delegate to application ports or use cases;
+* map application outcomes according to the applicable result-mapping standard.
+
+Controllers MUST NOT contain domain business rules.
+
+Controllers MUST NOT directly access:
+
+* JPA repositories;
+* `EntityManager`;
+* Hibernate APIs;
+* JDBC;
+* database connections;
+* persistence entities;
+* external service SDKs;
+
+unless such access is explicitly part of an approved adapter implementation and remains consistent with the established architecture.
+
+The expected dependency direction is:
+
+```text
+Inbound Adapter
+      ↓
+Application Port / Use Case
+      ↓
+Domain
+
+Outbound Technology
+      ↑
+Infrastructure / Outbound Adapter
+      ↑
+Application Port
+```
+
+---
+
+## 11. Error and Exception Handling
+
+This document does not define a separate API error contract.
+
+When the relevant AppWeaver capabilities are applicable:
+
+* exception handling MUST follow `global_exception_handler.md`;
+* error representation MUST follow `problem_details.md`;
+* application result-to-HTTP mapping MUST follow `result_mapping.md`.
+
+AI agents MUST NOT introduce an alternative API error response format solely for a new API version unless the project explicitly defines a new version-specific error contract.
+
+Internal implementation details MUST NOT be exposed through API responses.
+
+This includes:
+
+* stack traces;
+* internal exception details;
+* SQL statements;
+* database errors;
+* secrets;
+* access tokens;
+* credentials;
+* infrastructure implementation details.
+
+Error contract compatibility MUST be considered when evolving an existing API version.
+
+---
+
+## 12. Request Validation
+
+Request validation MUST occur at the appropriate API or application boundary.
+
+Jakarta Bean Validation MAY be used for API request validation when appropriate.
+
+Example:
+
+```java
+public record CreateProjectRequest(
+        @NotBlank String name,
+        @Size(max = 500) String description
+) {
+}
+```
+
+Boundary validation MUST NOT be used as a substitute for domain invariants.
+
+Domain invariants MUST remain enforced by the domain model and applicable domain rules.
+
+Validation behavior and validation error representation MUST remain compatible within a supported API version unless an approved compatibility change is introduced.
+
+---
+
+## 13. HTTP Status Codes
+
+API implementations MUST use HTTP status codes that accurately represent the API outcome.
+
+Common examples include:
+
+| Situation                                  |                                      HTTP Status |
+| ------------------------------------------ | -----------------------------------------------: |
+| Successful retrieval                       |                                              200 |
+| Successful creation                        |                                              201 |
+| Successful operation with no response body |                                              204 |
+| Invalid request                            |                                              400 |
+| Unauthenticated                            |                                              401 |
+| Forbidden                                  |                                              403 |
+| Resource not found                         |                                              404 |
+| Conflict                                   |                                              409 |
+| Validation failure                         | 400 or 422, according to the active API standard |
+| Unexpected server error                    |                                              500 |
+
+The exact response semantics MUST remain consistent within a supported API version.
+
+HTTP status selection and response construction MUST remain compatible with the applicable:
+
+* `problem_details.md`;
+* `result_mapping.md`;
+* authorization standards.
+
+---
+
+## 14. Authorization
+
+API versioning MUST NOT independently redefine authorization behavior.
+
+When authorization is applicable, API implementations MUST follow:
+
+`authorization.md`
+
+AI agents MUST NOT:
+
+* create an alternative authorization mechanism for a new API version;
+* bypass established authorization controls;
+* weaken authorization requirements without explicit approval.
+
+Changes to authorization requirements MUST be evaluated for API compatibility impact.
+
+---
+
+## 15. OpenAPI Documentation
+
+When OpenAPI documentation is used or required by the project, externally exposed APIs SHOULD be accurately documented.
+
+Documentation MUST accurately represent the applicable:
+
+* API version;
+* endpoints;
+* HTTP methods;
+* request contracts;
+* response contracts;
+* validation requirements;
+* HTTP status codes;
+* error responses;
+* authentication requirements;
+* authorization requirements where externally relevant;
+* deprecated endpoints or versions.
+
+Each supported API version MUST have an unambiguous OpenAPI representation.
+
+This does not require a separate physical OpenAPI document for every version.
+
+The chosen OpenAPI organization MUST accurately distinguish supported API versions.
+
+AI agents MUST update relevant API documentation when the published API contract changes.
+
+---
+
+## 16. API Deprecation
+
+Deprecated APIs or API versions MUST be explicitly identified.
+
+When available, deprecation information SHOULD include:
+
+* deprecated API version;
+* replacement API version;
+* migration guidance;
+* deprecation date;
+* planned retirement date.
+
+Example:
+
+```text
+/api/v1/projects
+
+Status: Deprecated
+Replacement: /api/v2/projects
+```
+
+Deprecated APIs SHOULD remain available for an appropriate transition period unless:
+
+* security requirements;
+* legal requirements;
+* operational requirements;
+* architectural constraints;
+
+require earlier retirement.
+
+---
+
+## 17. API Retirement
+
+A supported API version MUST NOT be removed without an approved retirement decision.
+
+Before retirement, the owning team SHOULD consider:
+
+* known consumers;
+* consumer migration status;
+* usage information, when available;
+* operational impact;
+* security implications;
+* replacement API availability;
+* contractual or organizational obligations.
+
+The retirement decision SHOULD be documented according to project governance requirements.
+
+---
+
+## 18. Testing Requirements
+
+Versioned external APIs MUST have appropriate automated tests based on the project's testing standards and the significance of the exposed contract.
+
+API tests SHOULD verify, where applicable:
+
+* endpoint availability;
+* HTTP methods;
+* request validation;
+* request and response contracts;
+* HTTP status codes;
+* error behavior;
+* authentication;
+* authorization;
+* version-specific compatibility;
+* deprecated API behavior when supported.
+
+Tests MUST preserve the architectural separation between the API boundary and the domain model.
+
+Integration tests SHOULD verify Spring Boot and Spring MVC behavior when framework integration is relevant.
+
+API tests MUST NOT require the domain model to depend on Spring MVC or other web framework types.
+
+---
+
+## 19. Modular Monolith Integration
+
+API versioning MUST respect the application's Modular Monolith boundaries.
+
+The AI agent MUST identify the module that owns the API capability before generating or modifying versioned endpoints.
+
+Versioned API contracts MUST remain associated with the appropriate owning module.
+
+API versioning MUST NOT be used to bypass module boundaries.
+
+AI agents MUST NOT:
+
+* access another module's internal repositories;
+* access another module's persistence implementation;
+* expose another module's internal domain entities;
+* duplicate domain logic across modules merely to support a new API version.
+
+Cross-module interaction MUST follow the application's established module contracts and architectural rules.
+
+The exact package location of versioned API components MUST follow the existing AppWeaver Java foundation and repository conventions.
+
+No Vertical Slice Architecture is implied or required by API versioning.
+
+---
+
+## 20. AI / AW-Spec Rules
+
+When API versioning is applicable, AI-generated API implementations MUST:
+
+* inspect existing API versions before creating or modifying an API;
+* inspect the owning module and its existing package structure;
+* determine whether a requested API change is breaking or non-breaking;
+* preserve the existing API version for backward-compatible changes;
+* introduce a new API version only when required by a breaking change or explicitly requested;
+* keep API contracts separate from domain and persistence entities;
+* preserve application and domain boundaries;
+* follow the established result-mapping mechanism when applicable;
+* follow the established exception-handling and Problem Details mechanisms when applicable;
+* follow authorization standards when applicable;
+* update relevant OpenAPI documentation when the published API contract changes;
+* add or update appropriate automated API tests;
+* preserve existing API behavior unless an approved specification explicitly changes it.
+
+AI agents MUST NOT:
+
+* create a new API version merely because implementation details changed;
+* expose domain or persistence entities directly through REST APIs;
+* place domain business rules inside controllers;
+* introduce API-version-specific dependencies into the domain model;
+* introduce Spring MVC dependencies into the domain layer;
+* redefine cross-cutting error, authorization, exception, or result-mapping mechanisms;
+* remove or modify an existing API contract without evaluating compatibility;
+* introduce speculative API abstractions without a defined requirement;
+* introduce a new top-level production package outside the AppWeaver Java foundation.
+
+---
+
+## 21. Forbidden Patterns
+
+The following dependency patterns are forbidden unless explicitly approved by the architecture:
+
+```text
+Controller → JPA Repository
+
+Controller → EntityManager
+
+Controller → Hibernate
+
+Controller → JDBC
+
+Controller → Database Connection
+
+Controller → Persistence Entity
+
+Controller → External SDK
+
+Controller → Domain Business Logic
+
+API DTO → Persistence Entity Exposure
+
+Domain Entity → API Version Dependency
+
+Domain Entity → Spring MVC Dependency
+```
+
+The preferred architectural direction is:
+
+```text
+Inbound Adapter
+      ↓
+Application Port / Use Case
+      ↓
+Domain
+
+Application / Domain
+      ↓
+Outbound Port
+      ↓
+Outbound Adapter / Infrastructure
+```
+
+The exact implementation MUST follow the predefined AppWeaver Java foundation.
+
+---
+
+## 22. Governance
+
+API versioning changes MUST comply with:
+
+* the active project constitution;
+* the AppWeaver Java foundation;
+* the Modular Monolith architecture;
+* the Hexagonal Architecture / Ports and Adapters rules;
+* applicable technology guardrails;
+* applicable application or module-specific rules;
+* generated AW-Spec specifications and design artifacts.
+
+Technology implementation details MUST NOT override architectural boundaries.
+
+Project-specific API behavior MUST be defined by the relevant application specifications and design artifacts rather than embedded in this common technology guardrail.
+
+Changes to this document MUST follow the applicable governance and constitution amendment process.
+
+---
+
+## 23. Summary of Standards
+
+When API versioning is applicable, AppWeaver Java applications MUST follow these principles:
+
+* URI-based major versioning is the default AppWeaver strategy.
+* API versions represent external contracts and remain outside the domain model.
+* Breaking changes require a new API version unless an approved compatibility strategy exists.
+* Non-breaking changes SHOULD remain within the existing API version.
+* API contracts MUST be explicit.
+* Domain and persistence entities MUST NOT be exposed directly through REST APIs.
+* API version-specific contracts MAY reuse the same application use case and domain behavior.
+* Controllers MUST act as inbound adapters and delegate to application capabilities.
+* Controllers MUST NOT contain domain business logic or directly access persistence infrastructure.
+* Error handling, Problem Details, authorization, and result mapping MUST follow their respective applicable AppWeaver guardrails.
+* API versioning MUST respect Modular Monolith module boundaries.
+* OpenAPI documentation, when applicable, MUST accurately represent supported API versions.
+* Supported external APIs MUST have appropriate automated API tests.
+* API versioning MUST NOT introduce Vertical Slice Architecture or an alternative top-level package structure.
+* All production code MUST remain within the predefined AppWeaver Java foundation structure.
+* AI-generated API changes MUST evaluate compatibility before modifying externally visible contracts.