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.

1 Like

Using meta seems correct to me.

1 Like

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…

With respect to the spec and it’s lack of bulk update support, I agree meta is the correct avenue without changing your model.

However, I would argue incorporating this into your resource model would be a better approach. You don’t want to bind your domain model to the constraints from the semantics of HTTP and {json:api}.

My suggestion is it would be best to have a submission only boolean attribute in your resource representation to “cascade_changes” or whatever makes most sense. Trying to do it “the {json:api} way” will result in a less optimal domain model. APIs are not databases over HTTP, the server is the source of truth and has the right to make changes to other resources whenever wants to do so.

Sorry for jumping in so late, I hope this may be of help!

1 Like