Open APIs

 View Only
  • 1.  TMF641 sync vs async

    TM Forum Member
    Posted Sep 29, 2019 12:21
    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?

    1. 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.
    2. 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).
    3. 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
    ------------------------------


  • 2.  RE: TMF641 sync vs async

    TM Forum Member
    Posted Sep 30, 2019 11:23
    Hello Alexandre

    Before to do deeply in your questions, I'm a bit surprised by your sentence: "However, a service order can be long lasting task (even including manual steps), for which an asynchronous request is more appropriate."
    Regarding my implementations (or the one we provided in ONAP externalAPI) , when a POST serviceOrder is triggered only 'surface' control are done on server side and the serviceorder resource is created. Client side get synchronously a 201 if everything look good (on surface)or 4xx if any issue.
    Then the service delivering begin. We can have issue at this time (eg: service specification provided did not exist, wrong service configuration, etc..) but the service Order is already stored and we use the service order & order item state to track this. Client side can pool the servcie order to get update or more efficiently subscribe to service order state change notification to get update. 

    Are we aligned on this orchestration ? I'm looking to your UC where the service order itself (independently to the service action requested) need asynchronous management.

    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    ------------------------------



  • 3.  RE: TMF641 sync vs async

    TM Forum Member
    Posted Sep 30, 2019 13:57
    Hello Ludovic,

    Thanks for the clarification. From your reply, I understand that from your experience, an Order request is by default always "asynchronous" in that it is not linked/synced with the fulfillment of the underlying ordered service(s) itself. I was instead thinking about an implementation where the serviceOrder resource is returned only once the ordered service(s) is fully completed (i.e. end-to-end synchronous with the final service).
    In the use case you describe there is indeed no need for a "monitor" pattern, as the order object (obtained almost immediately from the POST /serviceOrder response) can be polled at any time to get the progress and states of the various order items and associated services.
    So I think we are on the same page now.

    Btw, you refer to the "ONAP externalAPI", is it something we can access to (for REST requests examples, some implementation details or even source code)?

    Cheers


    ------------------------------
    Alexandre Meynaud
    Hewlett Packard Enterprise
    ------------------------------



  • 4.  RE: TMF641 sync vs async

    TM Forum Member
    Posted Oct 01, 2019 02:37
    Hello Alexandre

    Yes we're now aligned.
    About ONAP/ExtAPI you cant find documentation here: https://onap.readthedocs.io/en/latest/submodules/externalapi/nbi.git/docs/offeredapis/offeredapis.html

    Cheers
    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 5.  RE: TMF641 sync vs async

    TM Forum Member
    Posted Mar 28, 2022 10:25
    Updated link, latest and last ONAP Release with extAPI module:
    https://docs.onap.org/projects/onap-externalapi-nbi/en/guilin/offeredapis/offeredapis.html#offeredapis

    ------------------------------
    Matthieu GEEREBAERT
    Orange
    ------------------------------