Managing API versions

This article describes 10Duke Scale API versioning policies and compatibility rules that client applications must follow to ensure smooth operation across API updates.

API major version change policy

A major version change in the 10Duke Scale API occurs when breaking changes are introduced that are not backward compatible with the previous version. The following types of changes are allowed for a new (upcoming) major version:

  • Removal of API endpoints or operations
  • Changes to request or response data structures that break existing clients
  • Changes to authentication or authorization mechanisms
  • Modifications to core API behavior that affect existing integrations

Commitment and migration strategy

10Duke is committed to providing stability and predictability for API integrations:

  • Version stability: An API URL assigned to a Scale account will run the same API major version until that version reaches the end of life (EOL). API versions are long lived and the end of life is always communicated no less than six months in advance.
  • Migration control: Migration to a newer major version requires a decision to trigger allocation of a new API URL. Once the API URL has been assigned, the data migration can be started. 10Duke will provide automation and support for migrations. Note that a possible migration is not triggered by 10Duke.
  • Vendor responsibility: You, the software vendor, are responsible for triggering the migration to a new major version when ready.
  • No forced upgrades: 10Duke will not force customers to migrate until the current version reaches its announced EOL date.

For versions that have reached their announced EOL date, 10Duke may provide extended support for an additional fee. Contact 10Duke for more details.

API minor and patch version labeling

10Duke Scale release notes and API versioning refer to the major version only. The current major version is 1.

Minor and patch releases use a label consisting of the release date and a running number. This labeling format provides clear chronological tracking of releases:

  • Format: <date>.<patch number>
  • Examples: 2025-11-04.0, 2025-11-04.1, 2025-11-18.0, 2025-11-18.1

Minor and patch releases within the same major version maintain backward compatibility and do not introduce breaking changes.

JSON serialization and deserialization compatibility rules

Your client applications must implement robust JSON handling to ensure compatibility across API updates. The following rules must be followed:

Field handling

  • Missing fields: Your client applications must tolerate missing and undefined fields in model objects. A missing field should be treated as a null value for that field.
  • Unknown fields: Your applications must ignore fields that are not recognized in the response, allowing the API to add new fields without breaking existing clients.
  • Null values: Your applications must properly handle null values for optional fields.

Timestamp format

  • All timestamps are provided in ISO-8601 format with accuracy to seconds. As an example: 2025-01-15T14:30:00Z.

JSON serialization and deserialization requirements

Your client applications must implement JSON serialization and deserialization with the following behavior to ensure compatibility across API updates:

Serialization requirements

When sending data to the API, your client must:

  1. Empty objects: Allow serialization of objects with no properties (empty objects should serialize to {}).
  2. Date format: Serialize date/time values as ISO-8601 formatted strings (e.g., 2025-01-15T14:30:00Z), not as numeric timestamps.
  3. Timezone handling: Do not include timezone identifiers in date strings; use UTC with the Z suffix.

Deserialization requirements

When receiving data from the API, your client must:

  1. Unknown properties: Silently ignore any JSON properties that are not defined in your client’s data model.
    • The API may add new fields at any time without breaking your application.
    • Do not throw errors or fail when encountering unrecognized fields.
  2. Missing properties: Handle missing or undefined properties gracefully.
    • Treat missing properties as null or use appropriate default values.
    • Do not require all properties to be present in the response.
  3. Ignored properties: Do not fail when properties marked as ignored in your model appear in the JSON response.

Paging and filtering compatibility rules

The 10Duke Scale API may adjust paging parameters to optimize performance and resource usage. Your client applications must be designed to handle these changes.

The API references for 10Duke Scale License Checkout API and 10Duke Scale License Management API provide more details on the query parameters.

HTTP 429 (Too Many Requests) handling

The 10Duke Scale API may return HTTP status code 429 (TOO_MANY_REQUESTS) to protect system resources and ensure fair usage across all clients.

When 429 responses occur

  • The status code 429 may be added to any API endpoint on an as-needed basis.
  • This response indicates that the client has sent too many requests in a given time period (rate limiting).
  • The API may introduce rate limiting to new endpoints without prior notice as part of minor or patch releases.

On this page