Missing API documentation details: What is the format for the PATCH body?

[Johnson Earls]

The API documentation for the PATCH operation simply says "PATCH will update a single element".

This does not address what is expected in the body of the PATCH request and what the semantics of the PATCH request are -- in other words, what does PATCH do with the request body that it receives?

The examples in the individual API types are useless, since they are (i presume) auto-generated and include every single field with generic data.

So, how _exactly_ does PATCH work?  What information do you provide to it, and how does it use that information?

If this is following a "standard REST model", please give a pointer to the "standard REST model" that you are using, since there are a variety of methods used by different REST APIs for doing partial updates of an entity.

[Nayan Pandey]

Hi Johnson,

Thank you for contacting the StatusPage community!

We understand you wish to understand what is the format for PATCH body. 

As mentioned in the document, PATCH updates a particular resource partially as per the elements mentioned in the body of the API call.

For example, the below PATCH body would update the name and css_font_color  for a particular page that may have other elements as well but we are only updating the name and css_font_color in the below PATCH body. 

curl https://api.statuspage.io/v1/pages/{page_id} \
-H "Authorization: OAuth your-api-key-goes-here" \
-X PATCH \
-d "page[name]=string" \
-d "page[css_font_color]=string" 

You can refer to the PATCH API examples here.

Regards,
Nayan

[Johnson Earls]

Those examples (at least, the examples that are relevant -- the JSON examples, rather than curl which no one uses in automation) are useless as described in the initial ask:  they show every single field being passed.  Do all PATCH requests need to have every single field?

If so, PATCH is the same as PUT and therefore meaningless.

If not, my original ask stands:  What are the semantics of PATCH when passed a JSON object with only some fields filled out?  What about for object types that have nested objects, such as the `metadata` field of incidents - does PATCH replace the entire object, or does it only apply the fields I've filled out?  What about for object types that have a list, such as the `component_ids` field of incidents - does PATCH replace the entire list?

[Johnson Earls]

These types of questions are why I asked "exactly how does PATCH work"?  This needs to be documented exactly, not just with examples that either show a meaningless call (where every field is specified) or only show one simple example and don't cover all the situations where PATCH might be used.

[Nayan Pandey]

Hello Johnson,

As mentioned earlier, PATCH does not require every single field to be mentioned. You'd only need to mention the fields that you want to update. The example shared in the last response does not contain all the fields for the Page element and it only contains  name and css_font_color which is expected to be updated. Similarly, you can choose to keep the fields irrespective of the fact if you are using REST API or a curl command.

Additionally, the main difference between PATCH and PUT is that PATCH can be used for an existing element only where as PUT can be used to create an element if it doesn't exists as well. 

Regards,

Nayan

[Johnson Earls]

Nayan, you're correct that the example for "curl" does not show all the fields.  However, "curl" is the last tool I would choose when implementing automation for an API.  The JSON example does show all the fields.

And you still didn't answer the question about objects and arrays that are embedded in the top-level object.  How are those handled by PATCH?  This must be specified because there are different ways that embedded objects and/or arrays can be handled in an "update" process:

• a field with an embedded object in the PATCH can completely replace the same field in the source object; there can be a single level of recursion where the fields directly within the embedded object replace the fields within the source object, or it can be completely recursive, where each field within the embedded object no matter how deep will replace (or create) the equivalent field within the source object.
• a field with an embedded array in the PATCH can completely replace the source field; can be appended to the source field; can be treated as a set and only items that do not already exist in the source field are appended to it; or possibly other ways to merge two arrays.

[Nayan Pandey]

Hello Johnson, 

The usage of body in the PATCH command remains the same despite the tool being used to run the API. 

Here is an example for Update a component in the Postman tool: 

As per the example on the document, all the components are mentioned in the body where as here in the above example, we are only sending description and name in the body. 

In the response for the above API call, you can see that every other field remains the same except the description and name fields. 

Each filed will be updated as mentioned in the body of the PATCH command. If its an embedded field or a recursive field, it'll need to be mentioned within curly braces or as per the structure of the component and the command would update the resource accordingly. 

Let me know if that helps. 

Regards, 

Nayan

[Johnson Earls]

Nayan, thank you for the update.  What you showed above is NOT what appears in the API documentation (as I've said multiple times, the "JSON" examples show every field in the object and so are not usable as examples for "PATCH").

The question about how embedded objects and arrays are patched has still not been answered.  Your latest answer basically just said they had to be embedded in the request with the proper syntax.  That is not helpful.

My previous comment listed several different ways an embedded object or embedded array could be potentially handled by a "PATCH" operation.  This is why I said this documentation needs to be exact.  You can't just handwave and say "include the information in the right syntax".

API documentation needs to include both syntax (the structure of the information being passed) and semantics (what that information means): you've got the syntax (mostly, albeit not showing partial patch updates for JSON format), but not the semantics except in the most absolutely simplistic form of field descriptions - and even then, you don't say what the fields mean, but only what the contents can contain, so once again it's more syntax than semantics.

[Nayan Pandey]

Hi Johnson! 

Thank you for the response! 

I checked this internally with our development team as well saying that "All the PUT and PATCH APIs for updates are implemented in same way and they updates the record in place wherever applicable. Also, it depends on kind of the object when we decide to completely replace the array/nested object or update it recursively." 

You can also check this example -https://developer.statuspage.io/#operation/patchPagesPageIdIncidentsIncidentId
Along with the structure each field is explained. 

If you still have any further doubts, could you please give one example of the API and object that you are concerned about?

Regards,

Nayan

[Johnson Earls]

"It depends" is not a good answer when someone needs to know how to use your API from the documentation.

Once again, the example you give shows the entire object body in the "Payload" example, and does not give an example of changing just part of an embedded object or array.

So two examples based on the following `incident` object (only showing the relevant fields):

{
    "name": "test incident",
    "id": "incident_id",
    "...": "...",
    "components": {
        "comp1_id": "operational",
        "comp2_id": "operational"
    },
    "metadata": {
        "testing": {
            "field1": "some-value",
            "field2": "some-other-value"
        },
        "testing2": {
            "field3": "another-value"
        }
    }
}

First, if I do a PATCH with

{
    "components": {
        "comp1_id": "major_outage"
    }
} 

The two possibilities are that this replaces the entire "components" object, or just replaces the "comp1_id" field inside the "components" object.  Which?

Second, if I do a PATCH with

{
    "metadata": {
        "testing": {
            "field2": "a-different-value"
        }
    }
}

The three possibilities are that this replaces the entire "metadata" object, or replaces the entire "testing" object within the "metadata" object, or replaces only the "field2" value within the "testing" object.  Which?

This is the information that needs to be documented.

If the answer is "It depends", then EVERY such situation needs to be documented.  If it has consistent behavior, then that behavior can be documented in one place.

The same information needs to be documented for arrays.

As it stands, the API documentation is NOT USABLE since there is no way tell what information you need to provide to get a desired result.

[Nayan Pandey]

Hello Johnson, 

Thank you for sharing the examples! 

We totally understand the discrepancy in API doc here post reviewing the examples. We have created a ticket for document updation for the same with our internal team. 

Regards, 

Nayan