API Versioning & Deprecation Policy
API Versioning & Deprecation Policy
GAAPx provides deterministic, mission-critical financial automation. To ensure continuous stability for autonomous AI agents, ERP integrations, and financial systems, we enforce a strict versioning and deprecation lifecycle.
1. Versioning Strategy
- URL Path Versioning: All production and sandbox API endpoints include an explicit major version identifier in the path (e.g.,
https://api.gaapx.ai/v1,https://sandbox.gaapx.ai/v1). - Backward Compatibility: Non-breaking changes (such as adding optional request parameters or new response fields) are introduced seamlessly within the current major version (
v1). - Major Version Increments: Backward-incompatible changes trigger a new major version path (e.g.
/v2).
2. Deprecation Lifecycle & 180-Day Guarantee
When an endpoint or version is scheduled for retirement:
- Advance Notice: GAAPx guarantees a minimum 180-day deprecation notice period before any endpoint is retired.
- HTTP Deprecation Headers (RFC 8594): Deprecated endpoints return standard HTTP headers on every request:
Deprecation: @<timestamp>— The Unix timestamp when the endpoint was deprecated.Sunset: <http-date>— The exact GMT date and time when the endpoint will cease responding.Link: <https://docs.gaapx.ai/versioning>; rel="sunset"— Link to deprecation documentation.
- Machine Readability: AI agents and automated clients can programmatically monitor the
DeprecationandSunsetheaders to preemptively alert engineering teams.
3. Example Deprecation Response Headers
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Deprecation: @1790726400
Sunset: Wed, 01 Oct 2027 00:00:00 GMT
Link: <https://docs.gaapx.ai/versioning.md>; rel="sunset", <https://docs.gaapx.ai/openapi.json>; rel="service-desc"
RateLimit-Limit: 1000
RateLimit-Remaining: 999
RateLimit-Reset: 60
4. Current API Status
| API Surface | Current Version | Status | Deprecation Notice | Sunset Date |
|---|---|---|---|---|
REST API (/v1) | 1.0.0 | Active / Current | None | Continuous |
Product MCP Server (/mcp) | 2024-11-05 | Active / Current | None | Continuous |
Docs MCP Server (/docs/mcp) | 2024-11-05 | Active / Current | None | Continuous |
Sandbox API (https://sandbox.gaapx.ai/v1) | 1.0.0 | Active / Current | None | Continuous |
5. Migration Support
For assistance with migrating legacy endpoints or updating SDK versions:
- Review the OpenAPI 3.1 Specification
- Check Official Multi-Language SDKs
- Reach out to developer support at [email protected]