nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

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.

Accepted answers

All comments

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

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

cloud

statuspage

statuspage-cloud