Skip to main content

Versioning

The version is part of the path. The current and only version is v3:

Current version
https://lantfly.com/api/v3

What can change within v3​

Lantfly adds to v3 without a new version. Your client should accept:

  • new endpoints;
  • new optional request parameters and fields;
  • new fields in responses, and new keys inside details;
  • new values in lists of states and event types (for example a new webhook event or run origin);
  • new error codes. Fall back on the HTTP status for codes you don't know.

Don't rely on the order of keys in JSON objects, or on the exact text of message.

Breaking changes​

Removing or renaming a field, changing a type, or changing what an endpoint means would ship as a new version under a new path (for example /api/v4) next to v3, not as a change to v3.

Removed versions​

Older paths have been removed: /api/v1, /v2 (an earlier API) and /v3 without the /api prefix. Every request to them answers 410 with code api_version_removed, before authentication:

410 api_version_removed
{
  "error": {
    "code": "api_version_removed",
    "message": "…",
    "details": { "current": "https://lantfly.com/api/v3" }
  }
}

To migrate, call the same resource under /api/v3. Resources keep their IDs, and paths, keys and payloads in v3 are snake_case. Webhook payload templates written with old camelCase paths fill in empty values: rewrite them with the snake_case names (for example {{resource.default_dataset_id}}).

Tracking changes​

The OpenAPI specification always describes the live API. Regenerate clients from it, or diff it, to see what was added.