Hello,
I would like to raise the topic once again because unfortunately documentation and samples provided here are totally misaligned with the standards we have to comply to and hence are confusing. Simple example is TMF648 API PATCH sample. The patch request body contains just a single Quote Item which is intended to be patched (quantity to be changed from 10 to 15). The response returns 3 Quote Items instead of one and that is quite hard to imagine how they appear. Requirement to comply to
RFC 7386 - JSON Merge Patch is very strict and samples have to follow it! And such mistakes can be found in multiple API documents which confuses both customers and suppliers going to use APIs.
Another issue is an approach to management of list objects in the APIs in general. If we consider using JSON Merge Patch and not stick to JSON Patch (
RFC6902) then APIs brings a lot of overheads to both consumers and backend code in terms of array management. Consumers have to always put the whole array in the request in order not to have items deleted. Backend code has to always pick previous version of the resource from DB do diff and calculate deltas considering new version of the resource to apply to DB. Everything becomes slow and extremely complex. If we take as an example complex API like Quote Management this in fact makes consumer to know and understand Product Offering Catalog (including it's deep structure) on the same level as backend knows to make correct requests to backend. We are forced to bring this logic to consumer, which is a front-end quite often. This makes the API useless for frontends and we again forced to build up something graph QL like on top.
In general I personally do not understand why not to use maps instead of arrays (especially considering most of entities are supplied with IDs) or to make JSON Patch (RFC6902) being a mandatory to comply with. ------------------------------
Boris Khatkov
Netcracker Technology
------------------------------