Updating/Adding/Deleting Select Fields: JSON Patch

Version 3

    Background

    The HTTP verb, Patch, allows you to perform select operations on one or many fields of an entity as outlined in your JSON payload of your request, without needing to update the entire entity. Jive currently supports this method on a select number of endpoints (see Supported Endpoints and Operations), allowing you to perform listed operations on select fields. This allows for fewer requests since it is no longer necessary to perform a GET request first to grab the entire object at its current state and then perform a PUT request when only one or few fields need to be modified. For more details, please look at the official standard docs: RFC 6902 - JavaScript Object Notation (JSON) Patch. One of the biggest benefits to running a Patch operation is running a batch of updates in one request.

     

    Note: Currently only available on Jive Cloud

     


     

    Supported Endpoints and Fields

    /contents/{contentID} - Documents ONLY

    • Author

     

    /people/{personID}

    • Editable profile fields
    • Locale and Time Zones
    • Name
    • Emails
    • Phone Numbers

     

    /people/{personID}/tasks

    • Completed

     

    /places/{placeID}/tasks

    • Completed

     


     

    Request Header

    The header in a JSON Patch Request must contain Content-Type : "application/json-patch+json"

     


     

    Request Body

    The body sent in a PATCH request is a JSON array of operation(s) to perform. These are the properties according to the defined standards:

     

    Op (Operation)

    Add

      • If the path includes an array index, the new value is added to the entity at the specified index
      • If the path doesn't exist, a new member is created
      • If the path does exist, the value is replaced

     

    Remove

      • Removes the value at the described path

     

    Replace

      • Replaces the value at the described path with a new value. MUST contain a value parameter in the payload that has the same type as the field being replaced

     

    Move

      • Removes the value specified in the "from" parameter and inserts it to the described path

     

    Copy

      • Copies the value specified in the "from" parameter and inserts it to the described path

     

    Test

      • Compares the value at the path matches the value in the payload.
        • Must match JSON type (string, number, array, object, literals) and are considered equal in values that govern the type

     


     

    Path

    Path is required for all operations, is of type String, and references the location where the operation is to be performed.

     


     

    From

    Used only in move and copy operations, is of type String. The "from" object parameter is used to reference the originating value's location.

     


     

    Value

    Used only in add, replace, and test operations can be any JSON type (string, numbers, array, object, bool, null). This is the value to be inserted or compared during corresponding the PATCH operation.

     


     

    Performing a PATCH request

    It is highly recommended to perform a PUT request with a custom X-HTTP-Method-Override header set to PATCH due to restrictions from some host systems.

    Overview

    method : "PUT"
    headers : {
         content-type : "application/json-patch+json",
         X-HTTP-Method-Override : "PATCH"
    }
    body(array) : [{
         "op" : {{ add, delete, replace, move, copy, or test }},
         "path" :  {{ hierarchy in Jive service's entity }},
         "value" : {{ new value }}
    }]
    

     


     

    Example

    In this generic example of a CURL request, we'll be updating a custom Jive profile field of the current user's.

    curl -X PUT 
         -u "{{username}}:{{password}}"
         -H "Content-Type: application/json-patch+json" 
         -H "X-HTTP-Method-Override: PATCH"
         -d '[
                  {
                      "op" : "replace",
                      "path" : "/jive/profile/"{{custom field}},
                      "value" : {{new value}}
                  }
              ]'
         "http://{{Jive URL}}/api/core/v3/people/@me"
    

     

    Successful patch response: 200

     


     

    Error Handling

    Since all PATCH requests are atomic, if any of the operations in the array should fail, the whole operation will fail and no changes will be made. A great use of the test operation is to check for validity of a specific field's value and terminate the entire batch of operations due to it's failure.