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:: gluon-auth.rst
|
||||
.. include:: gluon-api-spec.rst
|
||||
.. include:: gluon_proton_versioning.rst
|
||||
.. include:: repo_structure.rst
|
||||
|
Loading…
Reference in New Issue
Block a user