Since the release of IBM z/OS Connect 3.0.87, support for PATCH in API requester has been made available in Open API 3 specification usage of z/OS Connect. What the HTTP PATCH method allows you to do is update a REST entity on a server on a field by field basis. With HTTP PUT we must update the complete entity even when only changing one field.
The four standard HTTP methods used in REST APIs are GET, POST, PUT, and DELETE. These methods retrieve, create, update, or delete a REST API resource respectively. When it comes to PUT the complete existing API resource is replaced by a new one supplied as part of the request.
When the resource is large and the change small there is a lot of unnecessary data transferred. This is where the PATCH HTTP method comes in. What PATCH states is for any REST API, an existing API resource can be updated on a property by property basis with the updates described by a Patch Document.
The PATCH method is described in the OpenAPI specification and by the HTTP RFC (Request For Comment). If you have not seen an RFC before, these are mini-specifications produced by the IT community which describe a particular IT facet. RFC5789 defines the HTTP PATCH method usage and how it can be used. It states that a Patch Document is used to update an existing REST API resource on a per property basis based on the media-type used for the request. What this RFC does not describe is what the Patch Documents look like. This is left to further RFC.
For JSON based Patch Documents, there are two RFC, RFC6902 for media-type application/json-patch+json, and RFC7396 for media-type application/merge-patch+json. These documents describe the format of the Patch Document to be sent to a REST API that supports a PATCH HTTP method.
The two RFC provide differing levels of support. RFC7396 JSON Merge (https://www.rfc-editor.org/rfc/rfc6902) is the simpler of the two and allows any number of properties to be updated, added, or deleted. An array property must either be completely replaced, added or deleted. For RFC6902 JSON Patch (https://www.rfc-editor.org/rfc/rfc6902), there is a greater fine grained control for arrays. A specific array element, or elements, can be identified and the properties of the element updated. There is no need to replace the complete array.
The good news is a CICS TS, IMS, or z/OS application (Batch) developer you do not need to know the details of these Patch Documents. z/OS Connect has the job of constructing these but there is added complication to the COBOL or PL/I application program. For an update from a PUT operation, the COBOL or PL/I request structure (Suffixed Q01) is fully populated with the data to update/replace the REST API resource. When using PATCH from a COBOL or PL/I program, we need a mechanism for the application program to tell z/OS Connect which properties and array elements are required to be updated and what the new content is. From this data, z/OS Connect can construct a Patch Document for the REST API PATCH operation to consume.
When the z/OS Connect API requester Gradle plugin is used to process an OpenAPI document for an API, when a PATCH method is defined, the plugin augments the request data descriptions with a property for each defined property. For media-type application/json-patch+json (RFC6902), rather than taking the data description from the OpenAPI PATCH operation, the data description is taken from a sibling PUT or POST operation. This is because for RFC6902 the Patch Document is defined as a mini-api and is the same for all APIs so the true API application data is sought from the sibling. This is not the case for media-type application/merge-patch+json (RFC7396) where the application data is described within the PATCH operation.
The generated COBOL or PLI will have fields suffixed -patch-operation and -patch-item. I’ll use the COBOL form in this blog. It is possible to shorten the field suffixes to allow greater space for the property name by setting the option shortSuffixes: true in the API requester Gradle plugin options file. In this case the names are -pchop and -pchitm.
An example request structure for media-type application/json-patch+json (RFC6902) is
01 BAQBASE-RBK02Q01.
03 requestPathParameters.
06 Xtitle-length PIC S9999 COMP-5 SYNC.
06 Xtitle PIC X(80).
03 requestBody.
06 title-patch-operation PIC X(1).
06 Xtitle2-length PIC S9999 COMP-5 SYNC.
06 Xtitle2 PIC X(80).
06 authors-patch-item PIC X(50).
06 authors2-num PIC S9(9) COMP-5 SYNC.
06 authors OCCURS 20.
09 firstName-patch-operation PIC X(1).
09 firstName-length PIC S9999 COMP-5 SYNC.
09 firstName PIC X(40).
09 lastName-patch-operation PIC X(1).
09 lastName-length PIC S9999 COMP-5 SYNC.
09 lastName PIC X(40).
06 status-patch-operation PIC X(1).
06 Xstatus-length PIC S9999 COMP-5 SYNC.
06 Xstatus PIC X(9).
06 formNumber-patch-operation PIC X(1).
06 formNumber PIC X(12).
06 licationDate-patch-operation PIC X(1).
06 publicationDate-length PIC S9999 COMP-5 SYNC.
06 publicationDate PIC X(32).
06 documentType-patch-operation PIC X(1).
06 documentType-length PIC S9999 COMP-5 SYNC.
06 documentType PIC X(8).
06 sizeMB-patch-operation PIC X(1).
06 sizeMB PIC 9(16)V9(2) COMP-3.
06 url-patch-operation PIC X(1).
06 url-length PIC S9999 COMP-5 SYNC.
06 url PIC X(100).
06 ngDepartment-patch-operation PIC X(1).
06 owningDepartment.
09 id-patch-operation PIC X(1).
09 Xid PIC X(5).
09 name-patch-operation PIC X(1).
09 name-length PIC S9999 COMP-5 SYNC.
09 name PIC X(40).
09 contact-patch-operation PIC X(1).
09 contact-length PIC S9999 COMP-5 SYNC.
09 contact PIC X(40).
When preparing to make a BAQEXEC call to a PATCH operation, the application must decide which properties and array elements are to be updated. The PATCH operation request structure is primed and then the BAQEXEC call made as normal. z/OS Connect will receive the binary data and transform this to JSON and create the Patch Document in the required format for the operations media-type. The REST API is then called and it will update the resource based on the Patch Document content.
For example, using the above structure we could make the following updates:
-
To update the formNumber property of the API resource we would move a new value in to formNumber and then set the value ‘U’ into formNumber-patch-operation. This setup is then indicating to z/OS Connect that the formNumber field contains a new value and is to be supplied to the REST API via the Patch Document.
-
To update an array element we use the -patch-item field to indicate which elements within the array are to be updated. The values supplied are indexed from one. The field contains a comma separated list of array elements to update, ranges can be supplied, and also a final ‘+’ character to indicate that new array elements are to be added.
For example, authors-patch-item could be set with the value ‘2, 4-7, +’ to indicate that array elements 2, 4, 5, 6, 7 are to be updated and that new array elements will be supplied and are to be added to the end of the array. So we are providing at least 6 array elements, so the authors2-num field is set to 6 to state that there are 6 array entries to process. Within each array element as part of the occurs clause, the fields that are required to be changed have their -patch-operation field set as required. e.g. set lastName-patch-operation to ‘U’ of element 1 in the array to indicate the lastName property of array element 2 to to be updated. The other array elements would have similar setups as required.
Any property where the suffixes of -patch-operation or -patch-item contain a space are not updated.
Any number of properties can be updated in one BAQEXEC call.
For full details on all of the types of updates that can be performed see the linked patch documentation.
IBM Documentation references
https://www.ibm.com/docs/en/zos-connect/zos-connect/3.0?topic=api-using-additional-properties
https://www.ibm.com/docs/en/zos-connect/zos-connect/3.0?topic=api-using-patch-in-application