# API versioning (/docs/basic-concepts/api-versioning)

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 [#the-version-in-the-url]

```text
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 [#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 [#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 [#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](/docs/basic-concepts/error-handling)).
- **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 [#next-steps]

<Cards>
  <Card title="API endpoint and requests" href="/docs/basic-concepts/api-endpoint" />
  <Card title="Errors" href="/docs/basic-concepts/error-handling" />
</Cards>
