Open APIs

Hi,

I am trying to design API notifications and I have some questions, because specifications and user guides are not everly detailed in this regard.

Let's say we have TMF622 API and the following events:

• ProductOrderCreateEvent

• ProductOrderAttributeValueChangeEvent

• ProductOrderStateChangeEvent

Now my primary concern here is about the payload and what happens when I have multiple changes to an order per transaction. The API specs states that the content of those events is just ProductOrder but examples in UserGuide suggest that it is not a full object, just a part of an object after the change:

• ProductOrderAttributeValueChangeEvent - contains only the changed attribbutes
• ProductOrderStateChangeEvent - contains only order Id + href and state (and itemStateChange which in fact is not mentioned in v5 swagger spec...)
• ProductOrderCreateEvent - contains a full order

So my questions are:

• Does this notifications have full value or delta semantics?
• What if in one logical operation I am changing multiple fields at once, I assume it's enough to emit one ProductOrderAttributeValueChangeEvent?
• What if in one logical operation (i.e. db transaction) I am changing the state (or any field for that matter, also a milestone) more than once (processes like orders can have automatic state transitions, so I may skip e.g.), do I have to emit many events? (I assume yes)

Hi Łukasz

Good question and it is one that has recently resulted in JIRA AP-6550 (Include Event patterns in TMF763 Gen5 Design Guidelines Part 7).  Part 7 is currently undergoing final review and should be released shortly.

Regarding your questions:

Does this notifications have full value or delta semantics? Answer: Currently it is a delta but the contents of the delta for each event type still needs to be agreed (in Part 7)

What if in one logical operation I am changing multiple fields at once, I assume it's enough to emit one ProductOrderAttributeValueChangeEvent? Answer: Correct, one event is sufficient for multiple changes (once again this will be clarified in Part 7)

What if in one logical operation (i.e. db transaction) I am changing the state (or any field for that matter, also a milestone) more than once (processes like orders can have automatic state transitions, so I may skip e.g.), do I have to emit many events? (I assume yes) Answer: Correct, you would require multiple events in this case.

Sorry I cannot help more at this time, but you won't have to wait long for a more precise answer.

Thanks.

It is very important to me as I am currently designing the generic event notification mechanism. 

One note though, the "delta" which can be expressed through partial snapshots is limited when it comes to field removal, let's say I have removed 1 order item, then I have to send a full list of order items? (without the removed item). My suggestion is that using JSON Patch might be much more effective here, I understand that this is a classical json patch vs merge-patch dilemma.

And one more thing, the filtering semantics.

I assume that any query e.g. "query": "[?(@.event.resource.status=='Resolved')]" is applied to the object snapshot after the modification (so I change status from new -> resolved and emit event with status:"Resolved". But when in the event body there is anything that did not change (and with JSON Merge-patch and collections there is, e.g. if I remove 1 order item I need to repeat all not removed), then the query semantics get blurry, because there are two possible:

• query applies to a change, so in the above example I only want ONE notification for every status CHANGE to "Resolved"
• query applies to an object after modification, so I get notification each time status IS "Resolved"

This is accidentally not a problem with status, but it is a problem when I would like to capture a change on any attribute, e.g. a characteristic set on a Product as a result of fulfilment etc. 

------------------------------
Łukasz Kubica
Comarch S.A.
------------------------------