Proton Version Management
Add Proton versioning specifications into doc folder. Change-Id: Iac04b61184601f9c8a96d44a370dbbac48bd73b3
This commit is contained in:
parent
629fd57ac5
commit
7843037629
157
doc/source/devref/gluon_proton_versioning.rst
Normal file
157
doc/source/devref/gluon_proton_versioning.rst
Normal file
@ -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, <some URL>/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"
|
||||||
|
...
|
@ -33,4 +33,5 @@ Gluon Developer Docs
|
|||||||
.. include:: database_migration.rst
|
.. include:: database_migration.rst
|
||||||
.. include:: gluon-auth.rst
|
.. include:: gluon-auth.rst
|
||||||
.. include:: gluon-api-spec.rst
|
.. include:: gluon-api-spec.rst
|
||||||
|
.. include:: gluon_proton_versioning.rst
|
||||||
.. include:: repo_structure.rst
|
.. include:: repo_structure.rst
|
||||||
|
Loading…
Reference in New Issue
Block a user