Using the PATCH HTTP method in an application

The PATCH HTTP method signifies that the REST resource is to be partially updated and not completely replaced, as is done with the PUT method. Both individual JSON properties can be updated and selected array items can be updated. This support is useful when the resource that you are updating is significant in size.

1. Preparing for the BAQEXEC call.
   When you prepare a PATCH call to an API, the BAQBASE-xxxnnQ01 language structure must be prepared to tell z/OS Connect which JSON properties are updated within the API resource. This update is done by setting specific values in the special fields that are suffixed -patch-operation and -patch-item that accompany the property fields. Then you supply a new value in the property field. Values of spaces in the suffixed fields indicate that no update is to be made to the related property. You can update multiple properties by using a single BAQEXEC call.

   Note: The -patch-item fields are only generated when the API PATCH operation uses the application/json-patch+json media-type. For application/merge-patch+json, -patch-operation field updates and controls the whole array.
2. Updating a root object property.
   Locate the property field that is to be updated and set a new value. In its sibling field that is suffixed -patch-operation set the value ‘U’ to denote the property is to be updated with a new value.
   For example, by using the fields from the Redbooks API sample. Update the Redbooks URL.

   
   MOVE 'U' TO url-patch-operation.
   MOVE 'http://newurl' TO url.
   MOVE 13 to url-length. 
   

3. Update a property in an object.
   To update a property within a property object is similar. You need to locate the property field that you want to update and set a new value. In its sibling field that is suffixed -patch-operation set the value to ‘U’.
   For example, to update the name property within the owningDepartment object, locate the 06 level owningDepartment language structure group, then find the name-patch-operation field.

   
   MOVE 'U' TO name-patch-operation.
   MOVE 'New Department' TO name.
   MOVE 14 TO name-length. 
   

4. Replace a complete object property.
   To update a complete object property, locate the language structure group that is named as the property. You have a sibling property with the same or similar name suffixed -patch-operation. Set this property to ‘U’. Then in each field within the group set a new value for the field. The sibling -patch-operation fields within the group can be set to space.
   For example, to update the complete owningDepartment property object. Locate the 06 level owningDepartment language structure group, then find its sibling owningDepartment-patch-operation field and set the value to ‘U’. Remember to use the shortSuffix Gradle plug-in option to show more detailed property names.

   
   MOVE 'U' TO ngDepartment-patch-operation.
   MOVE '00001' TO Xid.
   MOVE 'New Department' TO name.
   MOVE 14 TO name-length. 
   MOVE 'New Manager' TO contact.
   MOVE 11 TO contact-length.
   

5. Update a property in an array element.

   When you use RFC7396, array elements cannot be updated. You can replace only the complete array, just like any other property update. For this reason, the array field has a sibling field suffixed -patch-operation and updates are made as described earlier.

   When you use RFC6902, any array property has a sibling field suffixed -patch-item. This field is used to denote an array property you are updating or an element within the array that is being updated.

   Locate the array group within the language structure with its OCCURS statement. You have two sibling fields, one suffixed -patch-item, and one suffixed -num. Sometimes the sibling field -num can have a number that is suffixed to the property name. The -patch-item field is used to identify the elements within the array property that are to be updated as a comma-separated list of numbers or number ranges.

   For example, 1, 2, 5-7, +. If a new array element or elements are to be added then a final + is used within set of numbers, for example, 1, 2, 5-7, +. Elements are indexed from 1.

   The -num suffixed field is set with the number of array elements that are supplied within the OCCURS group to update the array property. A correlation exists between the -patch-item suffixed field and the -num suffixed field. If the field suffixed -patch-item contained 1, 2, 5-7, + then the -num field must contain the value 6 or greater and the OCCURS structure set with those 6 elements.

   For example, to update the last name of two of the Authors for a Redbook, locate the Authors array in the language structure. You can then update Author last name element 2 and Author last name element 4.

   
   MOVE '2,4' TO authors-patch-item.
   MOVE 2 TO authors2-num.
   MOVE 'U' to lastname-patch-operation(1).
   MOVE  'SMITH' TO lastname(1).
   MOVE 5 TO lastname-length(1).
   MOVE 'U' to lastname-patch-operation(2).
   MOVE  'MUNROE' TO lastname(2).
   MOVE 6 TO lastname-length(2).
   

6. Replace a complete array property element.
   To replace the entire content of an array property, the sibling -patch-item field is set to ‘REPLACE’. You set the sibling -num field to the number of elements that are defined in the language structure occurs group.
   For example, to replace the Authors array property content with 3 authors.

   
   MOVE 'REPLACE' TO authors-patch-item.
   MOVE 3 TO authors2-num.
   MOVE  'Liz' TO firstname(1).
   MOVE 3 TO firstname-length(1).
   MOVE  'SMITH' TO lastname(1).
   MOVE 5 TO lastname-length(1).
   MOVE  'John' TO firstname(2).
   MOVE 4 TO firstname-length(2).
   MOVE  'MUNROE' TO lastname(2).
   MOVE 6 TO lastname-length(2).
   MOVE  'Bob' TO firstname(3).
   MOVE 3 TO firstname-length(3).
   MOVE  'JONES' TO lastname(3).
   MOVE 5 TO lastname-length(3).
   

7. Delete a property.
   Locate the property field that is to be removed from an object. In its sibling field that is suffixed -patch-operation set the value ‘D’ to denote the property is to be deleted.
   For example, to delete the Redbooks documentType.

   
   MOVE 'D' TO documentType-patch-operation.

8. Delete an array element.
   Locate the array property field where you want to remove an array element. In its sibling field that is suffixed -patch-item set the array elements index value or values for the elements to be deleted. Then for each property that is defined within the array set the -patch-operation field to 'D' to denote the property is to be deleted. By setting all the property -patch-operation fields to 'D', the complete array element is deleted. Multiple array elements can be deleted at one time by specifying all the values in the -patch-item sibling field.
   In the following example, to delete the 4th element in the Authors array the 4 is stating we want to do something with the 4th element in the servers array. The 1 is saying that there is 1 element in the local COBOL occurs definition to be processed; delete in this case. The relationship between the two fields, for example is if -item is 2,3,4 then -num is 3.

   
   MOVE '4' TO authors-patch-item.
   MOVE 1 to authors2-num.
   MOVE 'D' TO firstname-patch-operation(1).
   MOVE 'D' TO lastname-patch-operation(1).
   

9. Delete an array property from an array element.
   Locate the array property field for which you want to remove a property from an array element. In its sibling field that is suffixed -patch-item, set the array element's index value or values for the elements where you want to remove a property.
   For example, to delete the 5th elements firstname property in the Authors array.

   
   MOVE '5' TO authors-patch-item.
   MOVE 1 to authors2-num.
   MOVE 'D' TO firstname-patch-operation(1).

10. Add a property.
    To add a property to an existing object, the object must be defined with an additionalProperties element within the OpenAPIs description of the PATCH operation's request body schema. This object definition generates a group in the language structure where additionalProperties can be set. See Using additionalProperties for details. Any additionalProperties set within the language structure of a PATCH operation are added to the object.

11. Optional: Replace an array - RFC 7396 only.
    With RFC 7396, the array manipulation capabilities are limited. The whole array property can be replaced or the whole array property can be deleted. In this example, you are supplying a new array with a single author. In RFC 7396, like the nonarray fields, the array has a corresponding -patch-operation field, in this case authors-patch-operation. To replace the array by using merge, you first set 'U' in the authors-patch-operation field. You set the authors2-num field to 1 to indicate that you have one array element in the replaced array.
    For example,

    
    MOVE 'U' TO authors-patch-operation.
    MOVE 1 TO authors2-num.
    MOVE 1 TO firstName-existence(1).
    MOVE 'NEW' TO firstName(1).
    MOVE 3 TO firstName-length(1).
    MOVE 'AUTHOR' TO lastName(1).
    MOVE 6 TO lastName-length(1).
    

12. Make the API call.
    When the PATCH operation request structure is setup for the API, make the BAQEXEC call as normal. z/OS Connect interprets the supplied request structure and constructs a patch document for the API operation based on the content structure and the specified media-type. This patch document is sent to the API operation by using a PATCH HTTP method. The API then interprets the patch document and applies the updates to the resource.