Technical Reference

Versioning

REST API Versioning

The Octave REST API version is represented by a version suffix in the URL of the all endpoints. This suffix has the following format: vX.Y, where X.Y is the version number. For example, the following endpoint URL indicates that the Octave REST API version is 5.0:

https://octave-api.sierrawireless.io/v5.0/my_company/group

All requests must include the version suffix in the endpoint URL. The major version always includes the latest minor and patch version.

Backwards Compatibility

Only backwards-compatible changes are included in the minor and patch versions.

Any backwards-incompatible changes are integrated in the next major version of the API (vX+1). The current API version is stable until its full deprecation. Here are the changes we consider as backwards-compatible and backwards-incompatible for Octave API:

Backwards-compatible Changes

  • Adding a new API interface
  • Adding a new HTTP binding to an interface
  • Adding an optional field to the request message
  • Adding a field to the response message
  • Adding a value to an enum in the request message
  • Changing Error message information in a response message

Backwards-incompatible Changes

  • Adding a value to an enum in the response message
  • Removing or renaming an interface, field, or an enum value
  • Changing an HTTP binding
  • Changing the type of a field
  • Changing visible behavior of existing requests
  • Adding a mandatory field to the request message

Domain Object Versioning

Certain domain objects (e.g., Cloud Actions, Edge Actions, Blueprints, Connectors, Files, etc.) are versioned. Additional endpoints are available to retrieve a specific version of the object.

GET https://octave-api.sierrawireless.io/v5.0/<company_name>/versions/<object_type>/<object_id>

When they are updated, the previous instance of the object is not deleted. Instead, a version field on the object is incremented and the previous version of the object is preserved for later retrieval. Versions of an object can be queried using the following REST API endpoint:

GET https://octave-api.sierrawireless.io/v5.0/<company_name>/versions/<object_type>/<object_id>/<version_number>

Where object_type includes: action, local-action, or blueprint.