Versioning

The version

The current version is v1, and it is part of every URL: https://api.closepact.com/v1/api. A version that changed how existing requests behave would get a new path, and v1 would keep answering as it does.

What can change in v1

These are additive, and can happen at any time without a new version or notice:

• New endpoints, and new resources.
• New optional request fields and query parameters.
• New fields in responses and in webhook payloads.
• New values in enums — a new deal stage, a new invoice status.
• New webhook event types.
• New error codes, for situations that could not happen before.
• Changes to the wording of message in errors.

Each one is listed in the changelog.

Breaking changes

These only happen in a new version, announced in advance in the changelog:

• Removing or renaming an endpoint, a field or an enum value.
• Changing a field's type or meaning.
• Making an optional field required, or adding a required one.
• Changing what an existing status code or error code means.

Something on its way out is first marked deprecated in the reference, with what to use instead, and keeps working for as long as the version it belongs to.

Building for change

An integration built this way keeps working through every additive change:

• Ignore fields you do not know. Do not reject a response, or a webhook, because it has more in it than you expected.
• Handle unknown enum values. Give every switch on a status or stage a default branch.
• Accept unknown events. Answer 2xx to webhook events you do not handle, and ignore them.
• Switch on error codes, not messages. error is stable; message is for people.
• Do not depend on order — of fields in an object, or of items in a list you did not ask to have sorted.