Open APIs

 View Only
  • 1.  202 Accepted

    TM Forum Member
    Posted Feb 05, 2021 09:46
    I've seen threads that mention some or maybe all of the ordering specs (622, 641, 652) used to have 202 Accepted on POST but that this has been removed in the current version of the specs.
    Can someone explain the background of why 202 would no longer be supported and whether that is something there has been discussion about re-introducing it?

    thanks,
    Lynn


    ​​

    ------------------------------
    Lynn Dueck
    Oracle Corporation
    ------------------------------


  • 2.  RE: 202 Accepted

    TM Forum Member
    Posted Feb 07, 2021 15:13
    Hi Lynn
    I don't have a causal explanation for the process, but I think that I can explain the logic.

    HTTP return status 202 implies that the request itself is being handled in an asynchronous fashion, i.e. (for POST) the entity is not "created" immediately.
    Most of the Open APIs are (presumably) being implemented in software, and there is no apparent reason why creation should take a significant amount of time, so significant that there would be no immediate response. Of course the state of the entity can change afterwards, due to processes, e.g. validation might not happen immediately. So the consumer should be prepared to consume entity state change events (for those APIs that raise such).

    Specifically for Service Activation (640) and Resource Activation (702), where the implementation is (likely) by network elements, it is plausible that there could be a significant delay in entity "creation", since the "creation" in this case is the actual activation of the service or the resource in the network equipment. These two APIs certainly should allow 202 response status.

    Having said that, I can understand why it might make sense for other APIs, e.g. asynchronous submission of an order via a message bus, so perhaps it should be reconsidered. It could be for more prosaic reasons, e.g. the Open API internal tooling not supporting generation of 202 in the swagger files.

    Let's see what other experts have to say, they might for example want to trash my argument :). @Ludovic Robert, @Vance Shipley, @Kamal Maghsoudlou

    Anyway hope it helps​​​​​

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: 202 Accepted

    Posted Feb 08, 2021 12:06
    Hello, 

    In addition to message bus based integrations, I think validation time may well be a justification for the use of 202.

    I agree one could create an order in a state which is pending business validation. However their might be rules which need to be checked prior to the order being created in that initial pending state. 

    If those validations require access to other business applications via APIs, and for some reason those applications are not accessible temporarily, so one is left with either rejecting the request to create an order or using 202 to suggest the resource creation is delayed. 

    202 would suggest the request has not failed but if you were to look for the order via a UI into the system of record you should not expect to see the order. 




    ------------------------------
    Derrick Evans
    ------------------------------



  • 4.  RE: 202 Accepted

    TM Forum Member
    Posted Feb 09, 2021 03:44
    Hello

    I share the requirements defined by Derrick but we moved in another directon to tackle it (and not use 202)

    We have now an Acknowledged state....so the idea is the following:
    1. Server receives a POST for a ServiceOrder for example
    2. Server does 'surface check' to check message basic stuff (mandatory field, datatype)
    3. Server answers  depending on this check:
      1. if error --> 4xx nothing is stored - game over
      2. if surface check ok --> 201 resources ; resource is id-ed, state is Acknowledged and of coure resource is stored.
    End of the 'synchronous transaction'

    Later the server will make the business validation - if there is an issue (the serviceSpecification did not exist in the catalog for example) then the order shifts to Rejected - a notification is triggered- game over for this order.

    We have in our backlog to define this lifecycle for all order API - it is done for the serviceOrder but probably not yet for the productOrder.

    With this pattern we have to keep 202 only for special case as described by @Jonathan Goldberg when the 'server' side is the resource itself. Note that in this case it could require the Monitor pattern.
    ​​Hope it helps

    Ludovic

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



  • 5.  RE: 202 Accepted

    Posted Feb 09, 2021 05:36
    Hello
    Interesting points. I can see the logic of reserving 202 for actual server side resources and can see how the proposed state model would work.

    ------------------------------
    Derrick Evans
    ------------------------------