Skip to main content
While our API is in beta status, Vetcove reserves the right to introduce breaking changes at any time. Where possible, we will provide advance notice of breaking changes via the changelog.

​
Overview

Our API follows a versioning strategy that allows for non-breaking enhancements within an existing version while ensuring that breaking changes are introduced only in new versions. This approach provides flexibility for iterative improvements while maintaining stability for existing integrations.

​
Versioning model

We use URL-based versioning, where the API version is included in the endpoint path (e.g., /v1/). Our approach consists of the following key principles: Non-Breaking Changes Within a Version
  • New fields may be added to responses or request bodies within the same version.
  • New optional query parameters may be introduced.
  • New endpoints may be added to enhance functionality.
  • Existing behaviors remain unchanged to ensure backward compatibility.
Breaking Changes Require a New Version
  • Changes that alter response structures, remove fields, or modify existing endpoint behavior in a non-backward-compatible way require a new major version.
  • These changes will be introduced in the latest versioned API (/v2/, /v3/, etc.), and you must explicitly call the new versioned endpoint.

​
Example: adding fields and endpoints

Suppose we introduce an additional field, delivery_status, in the response for the message endpoint: Existing Response (v1):
Updated Response (v1, Non-Breaking Change):
Since this is an additive change, existing API calls using /v1/message continue to function without modifications. Similarly, if we introduce a new endpoint (/v1/conversation), this does not require a new version since it does not impact existing functionality. New Endpoint (v2, Breaking Change): If we need to rename a field or change an existing behavior, a new version (/v2/) is required. For example, let’s say introduce the following breaking changes:
  • Renaming text to content
  • Modifying the return value of the delivery_status object
Since this change affects existing clients, /v2/ is introduced, and API calls must migrate to benefit from the updated behavior.

​
Best practices for developers

  • Use explicit versioning in API requests to ensure predictable behavior (/v1/, /v2/).
  • Expect additional fields in responses and design clients to ignore unknown properties.
  • Test new versions before upgrading, especially if breaking changes are involved.
  • For strong backward compatibility, avoid relying on undocumented behaviors or implicit assumptions about API responses.
By following this versioning strategy, we ensure a balance between innovation and stability, allowing developers to integrate seamlessly while maintaining API reliability.