API versions and deprecation

API versions

The API is offered in multiple versions. This allows the API to be changed in a manageable way as the features and design of Bonded Internet changes. When a new API version is introduced, older versions are deprecated but still supported for a period of time to allow partners to upgrade integrated applications.

The version is identified in the request URI. For example, the version 4 API is available at /api/v4/.

Some time after being deprecated, an API version will be removed. At least six months notice is given before removing an API version. API removals will be announced in the release notes.

The “self” API endpoint (i.e. /api/v4/self/) is considered a private API for the use of the Bonded Internet web application, and is not subject to these deprecation policies/index. Please avoid using it.

Addition of resources or fields

New resources and fields may be added to the current API version. Integrated applications should be written to handle new fields and resources gracefully—for example, by ignoring them.

Removal of resources or fields

A new API version will be issued if a field or resource needs to be removed. This could happen, for example, if a feature was removed from Bonded Internet. The new API version would omit the appropriate resources or fields, but older API versions would retain the resources or fields. If it was not possible for the API to return real data for the field, an appropriate type of dummy data would be returned. For example, suppose the CPE NAT IP feature was removed from Bonded Internet. A new API version would be introduced that omitted the cpenatips field from the bond resource. Older APIs would retain the cpenatips field but would return empty lists instead of the lists of CPE NAT IP objects.

Addition of field values

If a new value is added to the list of possible values for a field, a new API version will be issued. For example, if a new version of Bonded Internet adds a new type of leg, the API version will be incremented. Old API versions will continue to report the old field values. This ensures that new values will not be presented to existing applications that are not prepared to handle the new values.

Removal of field values

Values for a field may be removed from existing API versions. For example, suppose the PPPoE leg type was removed from Bonded Internet. Existing API versions would simply no longer return any PPPoE leg records for bonds.

Version history

Version Base URI Changes Introduced Deprecated Removed
1 /api/v1/
  • Introduced API
 2012.2 2015.1 6.3
2 /api/v2/
  • Added versions.
  • Bond resources includes nested child objects.
  • Updated field and resource names.
 2015.1 2015.4 6.3
3 /api/v3/
  • Added spaces.
  • Add users.
  • Added bond and leg tuning.
  • Introduced bonder name field.
  • Removed bonder customer and description fields.
  • Removed top-level statistics. Statistics are now found under spaces.
  • Added “warn” as a possible value in overall_state field for legs.
  • Removed “SSL initializing” as a possible value in overall_state for legs.
  • Added encryption_state field to legs.
 2015.4    
4 /api/v4/
  • Added IPv6 support.
 6.4