z/TPF REST Producer Multi Version Support

1. The introduction of z/TPF REST Producer Services at both Travelport and Delta Air Lines has revealed the need for Multi Version Support (MVS) support.
2. That is the need is to support multiple Major, Minor, and Patch Version combinations of a producer z/TPF REST Service at the same time.
3. IBM has recently introduced zREST changes that pass the REST Service's Universal Reference Locator (URL) path to both z/TPF Data Format Description Language (zDFDL) Middleware and the called z/TPF Provider Wrapper Application
a. These are both specified in the z/TPF REST Service Descriptor File (zRSDF).
4. zREST RFE Requirements to support Multi Version Support (MVS) are as follows:
a. Support for Major, Minor and Patch REST Service Schema Versions in producer z/TPF
i. A given zREST Service (zRESTSvc) must have Multi Version Support (MVS) supporting Major, Minor and Patch Versions Changes:
1. Major Versions (vn) change the arrangement, deletion, or location of elements within the zRESTSvc Schema's Substructures.
2. Minor versions (vn.n) simply add new elements or substructures to the end of existing Major Version's (vn) Schema's existing Substructures.
3. Patches are very minor corrections (vn.n.n) to a zRESTSvc and require a change of Swagger.
4. It is contemplated that the zREST Service's Base Path would include the Major, Minor and Patch Version Numbers.
b. zREST Service OperationID Uniqueness
i. Uniqueness within z/TPF of the zREST Operations Identifier (zOpID) would be achieved by concatenating both the zRESTSvc's Base Path, such as /zTPF/zRESTSvc/vn.n.n, and the current z/TPF REST OperationID.
ii. This would allow the Minor and Patch versions within a Major Version to use the same zOpID for the same REST Operation. z/TPF's need for REST OpID uniqueness would be satisfied with the concatenation of z/TPF's Base Path to the zREST Operation in addition to the zOpID specified within the zSwagger Document and the zREST Service Descriptor File (zRSDF).
c. zREST Service Descriptor File (zRSDF) would support reference to multiple versions of the producer z/TPF REST Open API Swagger Descriptor Documents (zSwagger)
i. Within the referenced producer zSwagger Document the OperationID would be as it is today allowing for the possibility of duplicate OperationIDs.
ii. This would be mitigated and uniqueness achieved by concatenating it with this Major/Minor/Patch Version's Base Path such as /zTPF/zRESTSvc/vn.n.n
d. Table look up of the z/TPF Provider initial Application Program Name based upon the zREST Service's Key e.g. Base Path.
i. This Base Path such as /zTPF/zRESTSvc/vn.n.n implies that the Major/Minor/Patch Version combination of the zREST Service would explicitly specify a unique z/TPF Provider Wrapper Application Program Name for each Major Version OR
1. Major/Minor/Patch Version Combination OR
2. One general z/TPF Provider Wrapper Application Program Name that would have conditional logic to manage Major/Minor/Patch Version combinations
ii. Currently z/TPF Provider Wrapper Application Program Name is specified in the zREST Service Descriptor File (zRSDF)
e. zREST Producer settings Name Value Pair (NVP) ISrvcName. (source Bradd Kadlecik)
i. Set as a default the Name Value Pair (NVP) ISrvcName to the operationId (zOpID)
ii. Set as a default a new NVP to the to the zRESTSvc's iSrvcPath Base Path (basePath)
iii. Ideally this allows the best of both worlds so that the z/TPF Provider Wrapper Application Program Name (zWrapper) concatenate the 2 into the ISrvcName if needed.
f. Dual zRESTSvc Base Path option providing Forward and Backward Compatibility between z/TPF's zREST Multi Version Support (MVS) and zREST prior to MVS (source Bradd Kadlecik)
i. IBM expects to have a dual path usage such that one can implement zREST support with the MVS and basePath based zOpID uniqueness and not.
ii. This would also allow for a migration path to MVS without having to revise and test previous deployed zREST Operations that do not MVS.
1. This causes something like tpf_srvcInvoke() which includes the operationId to now optionally include the basePath depending upon whether the zREST Operation's deployed Files support MVS or not.
iii. Add the "basePath" to the z/TPF service descriptor (ZRSDF) as an array of Base Paths. (source Bradd Kadlecik)
1. The array of Minor Versioned Base Paths could reference and easily reuse previously deployed files and wrapper programs that have not changed.
2. For example, the zDFDL remains the same between 2 Minor Versions and the newly deployed zRESTSvc Minor Version could point to the previously deployed zDFDL file.