=============================
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 <../../release-notes/index.html>`__.

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.                     2015.1       2015.4       6.3
                               - Bond resources includes nested
                                 child objects.
                               - Updated field and resource names.

--------- ------------------- ------------------------------------- ------------ ------------ ------------
 3         ``/api/v3/``        - Added spaces.                       2015.4
                               - 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.

--------- ------------------- ------------------------------------- ------------ ------------ ------------
 4         ``/api/v4/``        - Added IPv6 support.                 6.4

========= =================== ===================================== ============ ============ ============
