comecerodocs
Concepts

API versioning

How the Comecero API is versioned, which changes can arrive without notice in version 1, and how to write code that keeps working as the API grows.

The API version is part of the URL, and version 1 is the only one. This page explains what may change inside version 1 and how to write code that is not surprised by it.

The version in the URL

https://api.comecero.com/api/v1

v1 is the major version. There are no minor version numbers in the URL or in headers: every call to v1 uses the latest release of version 1.

Changes that can happen at any time

These changes keep old code working, so they can ship without notice:

  • New endpoints and new resources.
  • New fields on existing objects, including inside child objects such as formatted.
  • New optional query parameters and filters.
  • New values for fields that list types or statuses, and new error codes.
  • Fields appearing in a different order in a response.
  • A change in the length or format of the IDs Comecero creates.
  • Bug fixes, where the API did not behave as documented.

Changes that need a new version

These would break existing code, so they only come in a new major version, such as v2:

  • Removing an endpoint or a resource.
  • Removing or renaming a field.
  • Changing the format of key values such as dates and times.
  • Changing what an endpoint does in a way that conflicts with how it worked before.

Write code that keeps working

  • Ignore fields you do not know. Read the fields you need and skip the rest. Do not fail on extra fields.
  • Keep a fallback for every enum. A status or type can gain a new value. Treat an unknown value as "other" rather than crashing.
  • Keep a fallback for every error code. Branch on the HTTP status first, then on code (see Errors).
  • Treat IDs as opaque strings. Do not check their length or pattern, and store them in a text column with room to grow.
  • Do not depend on field order in JSON.

Next steps

On this page