1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
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()
|
