API Versioning

Overview

TotalAccess uses a dual-layer versioning strategy to ensure backward compatibility while allowing the API to evolve:

• Major versions are embedded in the URL path (/api/v1/, /api/v2/)
• Minor versions are negotiated via the X-API-Version date header

Major Versions (URL Path)

Major versions represent breaking changes:

• Removed fields from responses
• Changed field types
• New required request fields
• Removed endpoints or actions
• Changed authentication flow

When a major version is released, the previous version remains available for a minimum of 12 months before being sunset.

URL Convention

https://totalaccess.co.za/api/v1/public/data   ← Current (v1)
https://totalaccess.co.za/api/v2/public/data   ← Future (v2)

Minor Versions (Header)

Minor versions represent additive changes:

• New optional request fields
• New response fields
• New endpoints or actions
• New webhook events

Minor versions are date-based and negotiated via the X-API-Version header.

Usage

POST /api/v1/public/data HTTP/1.1
X-API-Key: ta_sk_xxxxxxxxxxxx
X-API-Version: 2026-07-01
Content-Type: application/json

{
  "action": "list-work-items",
  "limit": 50
}

Response Headers

All API responses include the version that handled the request:

HTTP/1.1 200 OK
X-API-Version: 2026-07-01
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 2026-07-22T12:01:00Z

Response Body

All API responses include meta.api_version in the response body:

{
  "success": true,
  "data": [...],
  "meta": {
    "api_version": "2026-07-01",
    "request_id": "req_abc123"
  }
}

Deprecation Policy

When an endpoint or action is deprecated:

1. The Deprecation: true header is included in responses
2. The Sunset header indicates when the endpoint will be removed
3. The deprecation is documented in the Changelog
4. A migration guide is published

Example Deprecation Response

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
X-API-Version: 2026-07-01

Deprecation Timeline

Migration Guide Template

When a major version bump occurs, a migration guide is published at /docs/migrations/v1-to-v2 with:

1. Removed fields — List of fields no longer returned
2. Changed fields — Fields with new types or formats
3. New required fields — Fields that must now be provided
4. New endpoints — Endpoints added in the new version
5. Code examples — Before/after snippets for common operations

Changelog

All version changes are documented in the Changelog.