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/v1v1 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
statusortypecan 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
Localized formatting
Add formatted=true to a Comecero API call to get money amounts and dates as display text in the shopper's language, and choose the locale with user_locale.
CORS
Call the Comecero API straight from a browser by adding your site's origin to the allowed CORS origins, and learn which origins are allowed without setup.