Skip to content
Netilion Developer Platform

API Versioning

The Netilion API is versioned to ensure that changes to the API will not break existing clients. The API version number is defined as MAJOR.MINOR.PATCH

  • MAJOR version: incremented for incompatible API changes
  • MINOR version: incremented for new functionality that is backward compatible
  • PATCH version: bumped for backward compatible bug fixes

Major version changes can break existing clients, minor and patch versions do not.

New major releases always result in new endpoint URLs that include the major version:

  • e.g. version 1: api.example.org/v1/asset/statuses
  • e.g. version 2: api.example.org/v2/asset/statuses

Old major versions will be kept until all clients have been migrated to a newer version or the support has ended, as defined in our terms & conditions.

Compatible changes

Compatible changes that do not break existing clients are to:

  • add endpoints
  • add optional request headers
  • make required request headers optional
  • add optional request url parameters
  • make required request url parameters optional
  • add optional request body attributes
  • add response body attributes
  • any changes to the response body of 400 responses that contain an error description

Changes to the structure of the request/response body are compatible if they only extend the existing schema and do not break the rules for attributes.

Incompatible changes

Incompatible changes that may break existing clients are to:

  • change response status codes
  • change response content type
  • remove or rename endpoints
  • add, remove or rename mandatory request headers
  • remove or rename optional request headers
  • change request header data types
  • make optional request headers mandatory
  • add, remove or rename required request url parameters
  • remove or rename optional request url parameters
  • change data types of request url parameters
  • make optional url parameters mandatory
  • remove or rename optional request body attributes
  • add, remove or rename required request body attributes
  • make optional request body attributes mandatory
  • remove or rename response body attributes

Structure changes to the request/response body are incompatible, if the structure gets a new hierarchy, parts are deleted, required attributes are introduced, attributes are renamed, or optional attributes are required.

(*) Removing response body attributes will not necessarily break a client, however it may cause to unwanted behaviour.