Hello,
The "Service Ordering Management API REST Specification" document does not discuss synchronous requests vs asynchronous ones (apart from notifications). And looking at the swagger definition, the only possible responses for a POST /serviceOrder are: 201 (sync success, with the full order as the response body) and the various error codes (400, 500). This give the impression that only sync requests are specified and possible.
However, a service order can be long lasting task (even including manual steps), for which an asynchronous request is more appropriate.
Also, the TMF "REST API Design Guidelines Part 1", probably applicable to all TMF APIs, describes the "monitor pattern" (in section 9), which is a way to deal with async requests. So here follows my understanding, can someone confirm or correct it please?
- There is no explicit way (i.e. special URL, dedicated request param) for a client app to request a sync or an async operation. The client app always performs the same POST /serviceOrder request and it is up to the server app to decide if the response will be sync or async. In case of a sync response, the client can end up waiting a very long time. Subject already discussed for TMF645.
- Two types of (success) responses are possible: 201 with a full sync response body, and 202 for an async response containing a reference to a "monitor" object that can then be queried back to get the progress/status of the service order. Note that this 202 response is not in the TMF641 swagger file (but only in the APIs design guidelines document). It is not clear if the monitor object should contain the order id, but must probably yes (even the monitor id and the order id can be the same in practice).
- The "hub/notifications" pattern ("REST API Design Guidelines Part 1", section 10) can be used to be notified throughout the order life-cycle, in particular once an order is created/completed. However, to be fully useful, the client application should know the "monitor" id, identifying a request (c.f item 2 above), to be able to correlate the received events to its past async requests. Then, the various event bodies should contain the related monitor id. Note: there is no monitor id in the "ServiceOrderCreateNotification" swagger definition, this maybe confirm that the monitor id and the order id should be the same.
Thanks a lot for your insights
------------------------------
Alexandre Meynaud
Hewlett Packard Enterprise
------------------------------