Docs
Versioning and deprecation
The API is versioned in the URL. This page is our policy for changes.
The version
Every endpoint lives under /v1. The version is part of the path, so you pick it by
the URL you call. The machine-readable description is
/v1/openapi.json and
the browsable one /v1/docs.
What stays compatible inside /v1
Changes that do not need a notice, because correct clients keep working. Write your code to tolerate them:
- New endpoints.
- New optional request fields and query parameters.
- New fields in responses and in webhook payloads. Ignore fields you do not know.
- New values of an enumerated field, including new error
types and new webhook event types. Keep a default branch. - Changes to
messagewording, to ids' internal content, and to the order of fields. - Limits can change with your plan; the current numbers are on Rate limits and Pricing.
What needs a new version
Removing an endpoint, field or event, changing what an existing one means or returns, making an
optional field required, or tightening validation so that a request which worked stops working.
Such a change is made in a new version (/v2), never inside /v1.
Deprecation
- When a new version is released, the old one keeps working for at least 12 months.
- Before an old version, endpoint or field is removed we give at least 6 months' notice by email to the account owner and team admins of the affected projects, and on this site.
- An urgent security fix may change behaviour sooner. We tell you what changed and why as soon as we can.
How you will hear
Notices go to the email addresses on your dashboard account. Questions about a change: support@giftingstack.com.
Questions or something unclear? support@giftingstack.com.