Versioning and deprecation
The Public API is versioned in the path: every endpoint of this version starts with /v1. This page explains which changes can reach v1 without notice, how a breaking change is introduced, and how to write a client that keeps working as the API grows.
Changes that can ship in v1
Section titled “Changes that can ship in v1”Grona adds to v1 without changing the version. These changes can appear at any time:
- new fields in responses, including new fields inside existing objects;
- new endpoints;
- new optional request parameters and body fields;
- new values in response enums, such as a new
status,script.status, variationtypeorerror.code.
Watch the Public API changelog for them.
Breaking changes
Section titled “Breaking changes”A breaking change is one that could stop a correct v1 client from working: removing or renaming a field or an endpoint, changing a field’s type or meaning, or making an optional parameter required.
Breaking changes ship under a new version path, such as /v2, never inside /v1. They are announced in the changelog before the old version is retired.
Write a client that keeps working
Section titled “Write a client that keeps working”Because v1 grows by addition, a client that follows these rules does not break when Grona ships a change inside v1:
- Ignore unknown fields. Do not fail when a response has a field you did not expect, and do not use strict schema validation that rejects extra properties.
- Handle unknown enum values. Give every
switchonstatus,script.status, variationtypeorerror.codea default branch. For an unknownerror.code, fall back to the HTTP status. - Do not depend on order. Do not depend on the order of fields in an object, or of campaigns in a list response. The one order v1 promises is
variations: creation order, Control before Test. - Do not parse ids or messages. Ids are opaque strings and error messages are for people.
- Send only the fields you mean to change. On update, leave out fields you are not changing so a new field’s default is never overwritten.
Stay informed
Section titled “Stay informed”Watch the Public API changelog for new fields, endpoints and announcements of new versions. For questions about a change, email support@grona.ai.