Versioning

Version Format

The API version format follows this pattern:

YYYYMMDD[-versionModifier][.releaseNumber]

Components

• YYYYMMDD: The release date in Year-Month-Day format (e.g., 20241910 for October 19, 2024).
• [-versionModifier] (optional): Indicates a pre-release version:
  • beta: Beta release
  • alpha: Alpha release
• [.releaseNumber] (optional): A build number for internal tracking.

Example Versions

• 20241119: General release from November 19, 2024.
• 20241210-beta: Beta release from December 10, 2024.
• 20241210.123456: Release with a specific build number.

Using the API Version

The version must be specified in the URL path of your requests.

Example (Using cURL)

curl -X GET "https://api.ocus.com/20241210/projects" \
-H "apiKey: <your_api_key>"

Example (Using JavaScript/Node.js)

const axios = require('axios');
// Version is part of the URL
axios.get('https://api.ocus.com/20241210/projects', {
  headers: {
    'apiKey': '<your_token>',
  },
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Client Guidelines for Versioning

1. URL Structure:

   Always format your API URLs as /{version}/{endpoint} (e.g., /20241210/projects)

2. Use Stable Versions:

   Always use stable versions (e.g., 20241210) unless you're testing beta features.

3. Avoid Hardcoding Versions:

   Use a configuration file or environment variables to store the version number. This makes it easier to update when new versions are released:

   TypeScript

   // config.ts
   export const API_VERSION = '20241210'
   
   // api.ts
   const apiUrl = `https://api.ocus.com/${API_VERSION}/projects`

4. Test Before Upgrading:

   When a new version is released:

   • Read the changelog for breaking changes
   • Test your integration in a staging environment first
   • Update your error handling to handle any new response formats
   • Verify all your critical API calls still work as expected

5. Handle Backward Compatibility:

   While backward compatibility is guaranteed for maintained versions, ensure your client gracefully handles deprecated fields or endpoints.

Discovering Supported Versions

The API exposes an endpoint to retrieve currently supported versions:

Request

GET /versions

Example Response

{
	"stable": "20x241119",
	"next": "20241210",
  "versions": [
        "20x241119",
        "20241210"
    ]
}

Version-Neutral Endpoints

Some endpoints don't require a version in the URL path as they are version-neutral. These are typically system-level endpoints that provide basic API information.

Example:

curl -X GET "<https://api.example.com/health>"