Skip to content
Start free Sign in

API versions and changes

Agency plan

Last updated

Available on the Agency plan

This feature is included in the Agency plan and the plans above it. See pricing

The version of the Kukie.io API is part of every address: https://api.kukie.io/v1. This guide explains what can change inside a version, how to write software that keeps working, and how a change that could break it is announced.

What can change at any time

Inside a version, the API can gain new operations, new members in an answer, new values for a member, and new optional parameters. These additions arrive without notice, because software written as below keeps working.

Write software that keeps working

  • Ignore members of an answer that your software does not know.
  • Treat a value your software does not know, such as a new status or a new error code, as an unknown case, not as a failure.
  • Decide by an error's code and HTTP status, never by the wording of title or detail.
  • Treat identifiers, API keys and cursors as opaque strings, and do not rely on their length or format.

Changes that could break your software

Removing or renaming an operation or a member, changing what a member means, or retiring a version is a breaking change. Section 8 of the API Terms holds the promise for such a change: how much notice you get, and that the notice comes in the answers of the affected operations, in the API changelog, and by email to the owner and the admins of the organisations whose keys called them in the period before the notice that the section names. Otherwise, behaviour that would break software comes only in a new version.

A security fix or a legal requirement can need a faster change. The API Terms cover that case too.

The OpenAPI document's version

The OpenAPI document at https://api.kukie.io/v1/openapi.json has a version number of its own, 1.9.0 when this guide was last updated. It is raised when the API's shape changes and is not the version of the API, which stays v1.

Was this helpful?

Listed on