From 7843037629087929024e52cbdcbcf652098dc3a9 Mon Sep 17 00:00:00 2001 From: Jin Li Date: Thu, 13 Apr 2017 15:23:52 -0700 Subject: [PATCH] Proton Version Management Add Proton versioning specifications into doc folder. Change-Id: Iac04b61184601f9c8a96d44a370dbbac48bd73b3 --- doc/source/devref/gluon_proton_versioning.rst | 157 ++++++++++++++++++ doc/source/devref/index.rst | 1 + 2 files changed, 158 insertions(+) create mode 100644 doc/source/devref/gluon_proton_versioning.rst diff --git a/doc/source/devref/gluon_proton_versioning.rst b/doc/source/devref/gluon_proton_versioning.rst new file mode 100644 index 0000000..f8c3ba7 --- /dev/null +++ b/doc/source/devref/gluon_proton_versioning.rst @@ -0,0 +1,157 @@ +============================= +Proton API Version Management +============================= + +Summary +------- + +Each Proton API set, e.g. L3VPN, may evolve over time. Proton API version evolves +independently of Gluon releases. Thus version management of Proton APIs plays an +important role to ensure the backward compatibility and forward compatibility of +applications and services that use particular Proton APIs. + +This document describes the mechanism of version management of Proton APIs. + +Proton Root URI +--------------- + +When the Proton root URI "/proton/" is accessed it will return a list of Proton APIs. + +.. code-block:: bash + + $ curl http://192.168.59.103:2705/proton/ + { + "protons": + [ + {"id": "net-l3vpn", + "status": "CURRENT", + "links": + [ + {"href": "http://192.168.59.103:2705/proton/net-l3vpn/", + "rel": "self" + } + ] + }, + {"id": "bgp", + "status": "CURRENT", + "links": + [ + {"href": "http://192.168.59.103:2705/proton/bgp/", + "rel": "self" + } + ] + } + ... + ] + } + +Proton Version Management +------------------------- + +Version information is appended to the root URL of a particular Proton, e.g. L3VPN. +For example, /proton/net-l3vpn/v1. + +When accessing the root URL of a particular Proton without version information, all +available versions of this Proton will be returned so that users can choose to use +a particular version of this Proton. + +When accessing the root URL of a particular Proton with version information, all +available resources in this version of Proton will be returned. + +Proton providers can specify version info in the proton model's yaml file. + +.. code-block:: bash + + $ curl http://192.168.59.103:2705/proton/net-l3vpn/ + { + "default_version": + {"id": "v1", + "status": "CURRENT", + "links": + [ + {"href":"http://192.168.59.103:2705/proton/net-l3vpn/v1/", + "rel": "self" + } + ] + }, + "versions": + [ + {"id": "v1", + "status": "CURRENT", + "links": + [ + {"href":"http://192.168.59.103:2705/proton/net-l3vpn/v1/", + "rel": "self" + } + ] + } + ], + "name": "net-l3vpn", + "description": "net-l3vpn description..." + } + +.. code-block:: bash + + $ curl http://192.168.59.103:2705/proton/net-l3vpn/v1/ + { + "resources": + [ + {"id": "interface", + "status": "CURRENT", + "links": + [ + {"href":"http://192.168.59.103:2705/proton/net-l3vpn/v1/interface/", + "rel": "self" + } + ] + }, + {"id": "port", + "status": "CURRENT", + "links": + [ + {"href":"http://192.168.59.103:2705/proton/net-l3vpn/v1/port/", + "rel": "self" + } + ] + }, + {"id": "vpn", + "status": "CURRENT", + "links": + [ + {"href":"http://192.168.59.103:2705/proton/net-l3vpn/v1/vpn/", + "rel": "self" + } + ] + }, + {"id": "vpnafconfig", + "status": "CURRENT", + "links": + [ + {"href":"http://192.168.59.103:2705/proton/net-l3vpn/v1/vpnafconfig/", + "rel": "self" + } + ] + }, + {"id": "vpnbinding", + "status": "CURRENT", + "links": + [ + {"href":"http://192.168.59.103:2705/proton/net-l3vpn/v1/binding/", + "rel": "self" + } + ] + } + ] + } + +**Example** + +:: + + file_version: 1.0 + imports: base/base.yaml + info: + name: net-l3vpn + version: 1.0 + description "L3VPN API Specification" + ... \ No newline at end of file diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index 30464b2..d8e6b32 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -33,4 +33,5 @@ Gluon Developer Docs .. include:: database_migration.rst .. include:: gluon-auth.rst .. include:: gluon-api-spec.rst +.. include:: gluon_proton_versioning.rst .. include:: repo_structure.rst