Versioning

The API version is part of the URL path, so it is always obvious which contract a request uses.

Versions in the URL

Every endpoint currently lives under https://api.aveecare.com/v1. A future incompatible redesign would be published under a new prefix such as /v2, and /v1 would continue to exist alongside it.

Compatible changes

These changes can happen inside /v1 without a new version:

• Adding a new endpoint.
• Adding a new optional request field or query parameter.
• Adding a new field to a response object.
• Adding a new value to an enum or a new error code.

Announcements appear in the changelog.

Writing resilient clients

• Ignore response fields you do not recognise.
• Do not assume an enum is closed. Handle unexpected values gracefully.
• Do not depend on the order of fields in JSON objects.
• Treat IDs and cursors as opaque strings.

Requests are stricter than responses: the API rejects fields it does not know with the unknown_field error rather than silently ignoring them, which catches typos early.