cascaded updates in event driven APIs

[Hari Govind V K]

 While sending out webhook notifications from the server (as opposed to pull REST api) how do we model parent child relationships ? Should the change in child entity be represented as both a child update as well as a parent update ?

example: In the case of an article and comments associated with the article, the JSON representation could be :

{

"articleId" : 1231,

"articleContent" : "content string",

"articleComments" :[

            {

"commentId" : 1,

"commentContent" : "this is the first comment",

            },

            {

"commentId" : 2,

"commentContent" : "this is the second comment",

            }

    ]

}

If  a comment add event were to occur, it can be interpreted in two ways :

1) A pure comment add event, where the payload may or may not contain the details of the article

2) An article update event, where we have successfully represented the relationship between comment and article but have obscured what actually happened.

 

We currently used the first way and used hypermedia formats to represent the relationships. Is there a better way to do this ?

[Andrew B]

We have this situation a lot, and we settled on normally on mostly only sending the fact that an update occurred - not what it was.

rationale:

Say we are dealing in a resource of "article", which includes within that resource the article's text (which can be large - many KB) and some tags (I didn't pick comments as per your example because you could argue both ways as to whether a comment is part of the article resource or a resource of its own).

Now say we have various microservices that care about articles in different ways - e.g. microservice A only cares about articles' tags, whereas B only cares about the text.    

When an article is updated, we could send out a notification (webhook) including the updated data. But in the case where the text is updated, that would mean that microservice A would receive that notification and all the KB of article text, even though it doesn't care about the article's text at all. That means unnecessary processing by A, and unnecessary network traffic (lots of it for large articles) into A.

This leads to the conclusion that, at least for resources that have more than a few bytes worth of data, you need to do something smarter, e.g.:

- some kind of fancy pub/sub where you register your webhook as being only interested in certain changes to the resource

- send a blanket notification out, then apps pull only the data they care about, e.g. A will only pull the tags, and then only if they have changed

- etc.

There are sometimes other weirdnesses to do with notifications arriving out of sequence that make the pull approach better as well.  

That was all a bit long winded, and maybe only tangentially related, but to get to your question, I'd say the way you are doing it now is potentially sending unnecessary network traffic. If all that has happened is that a comment has been added, then why not just send the added comment?

Unfortunately rfc7396 (json merge patch) doesn't quite handle your case, but rfc6902 might work:

PATCH /articles/1231

[

    { "op": "add",

      "path": "/comments",

       "value": {

           "commentId" : 2,

           "commentContent" : "this is the second comment"

       }

    }

]

[mca]

yep - martin fowler recently wrote about various "event" style interfaces to consider.

your example is covered, i think.

https://martinfowler.com/articles/201701-event-driven.html

mca

Mike Amundsen

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

http://g.mamund.com/meetme

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+unsubscribe@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Andrew B]

That's a great article, and quite the rabbit hole!

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.