How to pass "special instructions" in update resource request?



I’m struggling to find the “correct” way to do the following with JSON.API:

When updating a resource field, I want to provide an option to allow propagation of the changes to some linked resources.

Here’s a real-world example:

I have a “ChildCategory” resource potentially linked to a “ParentCategory” resource. The child category allows the possibility to override a value from the parent/default category. When I update the ParentCategory, I want to give the option to propagate the value change to all child categories that are linked to that parent category. Sort of like a bulk update.

In the UI, it would look like a confirmation popup asking “Would you like to also update the linked child categories?”

What is the proper way to do this? I’m thinking maybe using the “meta” information. But that seems a bit weird:

PATCH /api/parentcategories/{id}

    "data": {
        "type": "ParentCategory",
        "id": "parent1",
        "attributes": {
            "value": 54321
    "meta": {
        "propagateToChildren": true

To other way I’m thinking is to manually update each and every child category linked to the parent in a separate request, but that seems like over complication of the app. A simple parameter should suffice.

Any thoughts? Thanks.


Using meta seems correct to me.


Or you could add a query parameter to the URL?


@dougo, yes that works too, but I think that a URL parameter is a “hackier” workaround that a meta field.

Maybe it’s more of a philosophical point of view, but I’m thinking that if the URL is representing a resource you are PATCHing to, then a querystring parameter should be about that resource, not about a side-efffect the PATCHing should have. The request body is the content of the PATCH operation, so a meta tag is information about that operation…

That being said, I am struggling to be JSON API compliant and I often find myself naturally tending toward more “rpc/action-oriented” URL and payloads…


I guess I was thinking that it’s actually two different resources, ParentCategory vs ParentCategory+ChildCategories, and the resources could be differentiated by having different URLs. You could even have the parameter be “include=children” and that URL could also be used to retrieve all the ChildCategories as included objects in the JSON-API document. But maybe that’s a little too cute…