aboutsummaryrefslogtreecommitdiffstats
path: root/standardization/docs
diff options
context:
space:
mode:
Diffstat (limited to 'standardization/docs')
-rw-r--r--standardization/docs/custom_header.rst86
-rw-r--r--standardization/docs/index.rst11
2 files changed, 97 insertions, 0 deletions
diff --git a/standardization/docs/custom_header.rst b/standardization/docs/custom_header.rst
new file mode 100644
index 00000000..59014aa4
--- /dev/null
+++ b/standardization/docs/custom_header.rst
@@ -0,0 +1,86 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 vmware
+
+1. Background
+=============
+
+Trouble shooting and tell client the latest api version under that major version is requested.
+
+2. Propose
+==========
+
+https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines
+
+3. HLD
+======
+
+3.1 Version Management
+----------------------
+
+Every component provides a json file or property configuration which is used to describe the api version detail. The example of json file content as:
+{
+"apiVersion":
+{
+"eventListener":["4.7.2","5.3.2","5.4.1","7.0.1"],
+"xxxxxx": ["1.0.2","1.1.2","2.0.1"]
+}
+}
+
+============== ============== =====================================================================================================================================================================================================================================
+**Field** **Value type** **remark**
+apiVersion Map An identify that start to describe the api versions
+eventListener Array<String> A service, resource or function name of component, which is a unique identify of one api. Requirement: describe the api version in sequence that is from first version to greatest version.
+============== ============== =====================================================================================================================================================================================================================================
+
+In the future, if there are other version configurations which need to be described, extend other fields.
+
+3.2 Return response with custom headers
+---------------------------------------
+
+First, server should check the custom header of client, if X-MinorVersion does not exist which is maybe deletes after a period time or that client requests is wrong because of some reason, return response with errorcode 400 and the first major version including X-MinorVersion, X-PatchVersion, X-LatestVersion.
+
+3.2.1 Minor version non-exist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For exmpale, ves has no 5.2.x version, so if the request of client is major version v5, X-MinorVersion is 2, the server return with 400 errorcode and custom headers including X-MinorVersion 4, X-PatchVersion 1, X-LatestVersion 5.4.1
+
+=========================== ================== ================== ================== =================== ======================================================================================================================================
+**Client send** **Server return**
+=========================== ================== ================== ================== =================== ======================================================================================================================================
+**major version requested** **X-MinorVersion** **X-MinorVersion** **X-PatchVersion** **X-LatestVersion** **remark**
+v5 2 4 1 7.0.1 Fail to valid, return 400. X-MinorVersion and x-patchversion are under the last version that the major version is requested by client.
+=========================== ================== ================== ================== =================== ======================================================================================================================================
+
+3.2.2 Minor version exist
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+=========================== ================== ================== ================== =================== =====================================================
+**Client send** **Server return**
+=========================== ================== ================== ================== =================== =====================================================
+**major version requested** **X-MinorVersion** **X-MinorVersion** **X-PatchVersion** **X-LatestVersion** **remark**
+v5 no 3 2 7.0.1 Supported request; X-MinorVersion and x-patchversion are under the first version that the major
+v5 4 4 1 7.0.1 Valid request; respond with customer header
+v5 3 3 2 7.0.1 Valid request; respond with customer header
+v7 no 0 1 7.0.1 Supported request; notify client with customer header
+v7 0 0 1 7.0.1 Supported request; notify client with customer header
+=========================== ================== ================== ================== =================== =====================================================
+
+3.3 Code Implement
+------------------
+
+CustomHeaderUtils is a class that provides functions to validate the X-MinorVersion which client requests and return the response header according to the client request.
+
+The usage example:
+------------------
+CustomHeaderUtils util = new CustomHeaderUtils(requestMajorVer, reqHeaderMap, filePath, "eventListener");
+
+
+// check request header
+
+util.isOkCustomHeaders();
+
+
+// get response header
+
+Map<String, String> rspHeader = util.getRspCustomHeader() \ No newline at end of file
diff --git a/standardization/docs/index.rst b/standardization/docs/index.rst
new file mode 100644
index 00000000..33e23991
--- /dev/null
+++ b/standardization/docs/index.rst
@@ -0,0 +1,11 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2019 vmware
+
+ONAP API Standardization
+========================================
+
+.. toctree::
+ :maxdepth: 1
+
+ custom_header.rst \ No newline at end of file