Keep track of changes to the Youtrust API
API version controls the API and webhooks behavior you see (what resources you can request, what properties you see in responses, what parameters you’re allowed to send in requests, and so on).
Youtrust API use semantic versioning, API major version is part of the URL path https://api.yousign.app/{version}
Example for the current version (v3) : https://api.yousign.app/v3
Each time a non backward compatible change (breaking change) is introduced to the Youtrust API, a new major version is released.
Backwards Compatible Changes
A backwards-compatible change is a change in the Youtrust API contract.
The following changes are considered backward compatible and do not trigger a new major version. They can be introduced at any time, on any endpoint, without prior notice or announcement:
- Adding new API resources/endpoints.
- Adding new optional request parameters to existing API endpoints.
- Adding new properties to existing API responses.
- Changing the order of properties in existing API responses.
- Changing the length or format of strings, such as object IDs, error messages, and other human-readable strings.
- IDs will never have length greater than 255 characters.
- Error detail may change but not the type of the error.
- Adding new event types on our Webhooks.
When an endpoint or a property is deprecated, you don't need to change anything in your code, it will still work and it is not planned to be suppressed.
We give you the new property name and it should be used for new implementations. Indeed, we advice to use the new property to remain compatible with future versions of the API
Build a Resilient Integration: Tolerant Reader Pattern
Because backwards-compatible changes can appear at any time, your integration must be designed to handle them gracefully. We recommend implementing the Tolerant Reader pattern:
- Ignore unknown fields in API responses instead of failing when an unexpected property is encountered.
- Avoid strict schema validation that rejects responses containing fields you haven't seen before.
This is especially important for JSON parsing: only extract the fields your integration explicitly needs, and discard the rest without error.