API Versioning

Accuris APIs use date-based versioning to manage changes and ensure backward compatibility. This allows you to control when your application adopts API changes.

Version Format

API versions follow the YYYY-MM-DD format (e.g., 2025-09-18). Each version represents the API as it existed on that date.

Specifying the API Version

You must specify the API version in your requests using HTTP headers. The header used depends on whether your request includes a body:

• Requests with a body (POST, PATCH) - Use the Content-Type header
• Requests without a body (GET, DELETE) - Use the Accept header

Header Format

Include the version as a parameter in the header:

Content-Type: application/json;v=2025-09-18
Accept: application/json;v=2025-09-18

Example: GET Request

GET /industrial/document/standard
Authorization: Bearer {access-token}
Accept: application/json;v=2025-09-18

Example: POST Request

POST /industrial/document/standard
Authorization: Bearer {access-token}
Content-Type: application/json;v=2025-09-18

{
  "title": "Example Standard"
}

Important Rules

Use Consistent Versions

Always use the same API version across all requests in your application. This ensures consistent behavior and prevents compatibility issues.

Matching Headers

If your request includes both Content-Type and Accept headers with versions, they must be identical. If they differ, the server will reject the request with 400 Bad Request.

Default Behavior

If you omit the version from a request, the server will default to the latest available version. This is not recommended for production applications as it can lead to unexpected breaking changes when new versions are released.

Server Version Handling

Version Fallback

If you request a version that doesn't exist, the server will automatically fall back to the nearest older version it supports. This ensures your application continues to work even if a specific version is unavailable.

Response Version

The server indicates which version it used in the response's Content-Type header. Always check this to confirm which version was actually used, especially when relying on fallback behavior.

Example: Version Fallback

Request:

PATCH /industrial/document
Authorization: Bearer {access-token}
Content-Type: application/merge-patch+json;v=2025-09-18

{
  "delete": [
    {
      "@id": "https://accuris.io/industrial/document/AAAA",
      "version": 5
    }
  ]
}

Response:

HTTP/1.1 200 OK
Content-Type: application/ld+json;v=2025-09-01

{
  "delete": [
    {
      "@type": "https://accuris.io/edm/schema/content/Document",
      "@id": "https://accuris.io/industrial/document/AAAA"
    }
  ]
}

In this example, the server didn't have version 2025-09-18, so it fell back to 2025-09-01 (the nearest older version).

Invalid Version Format

If you provide a version in an unrecognized format, the server will respond with 400 Bad Request.

Best Practices

• Always specify a version - Don't rely on the default version in production
• Pin to a specific version - Choose a version that works for your application and stick with it
• Test before upgrading - When a new version is released, test your application thoroughly before updating
• Monitor response headers - Check the Content-Type header in responses to confirm which version was used
• Plan for deprecation - Stay informed about version deprecation timelines and plan upgrades accordingly