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 SD-WAN 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 SD-WAN 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
SD-WAN. 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
SD-WAN. 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 SD-WAN 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 SD-WAN. Existing API versions would simply no longer return any PPPoE leg records for bonds.
Version history¶
Version |
Base URI |
Changes |
Introduced |
Deprecated |
Removed |
|---|---|---|---|---|---|
1 |
|
|
2012.2 |
2015.1 |
6.3 |
2 |
|
|
2015.1 |
2015.4 |
6.3 |
3 |
|
|
2015.4 |
||
4 |
|
|
6.4 |