Compatibility policy

The /v1 in every path is the API version. Lazy keeps /v1 working for the integration you build today. This page says which changes can still happen within /v1, so your code can tolerate them.

Changes Lazy may make within /v1

Lazy may make these changes at any time, without a new version. Write your code so it keeps working when they happen:

• New endpoints.
• New fields in responses, including in the error envelope. Ignore fields you do not know.
• New optional request fields and query parameters. Requests you send today stay valid.
• New values in a field that holds one of a fixed set of values. Handle a value you do not know without failing.
• New error codes. Handle an unknown code by its HTTP status.
• New response headers.
• Changes to error message text. Branch on code, never on message.
• Changes to cursor contents. Cursors are opaque; pass them back unchanged.
• Changes to the order of fields in a JSON object.

Every change is listed in the changelog.

Changes that need a new version

Lazy does not make these changes within /v1:

• Removing or renaming an endpoint, a field, or a query parameter.
• Changing a field’s type, or making a response field that is never null nullable.
• Making an optional request field required, or adding a required request field.
• Changing what an existing field or status code means.

A change like this ships under a new version, such as /v2, next to /v1. Lazy announces it in the changelog before it ships.