TM Forum Community

 View Only
Expand all | Collapse all

ServiceOrderingManagement_POST Idempotency

  • 1.  ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 14, 2019 11:19
    ​Dear all,

    I sought for help about the ServiceOrderingManagement in regards to Idempotency using operation. Currently we are using POST.


    Idempotence is when a service is accessed several times with identical access parameters, the same return value is always returned as the very first time it was accessed.
    POST method is usually used to create a new data record.  Will this does not satisfy the requirement of idempotence? If not which http(s) methods (e.g.,  GET, PUT, DELETE) will fulfill this requirement by definition?

    Thanks in advance for your prompt answer!

    Cheers
    Erlina


    #TMForumGeneral

    ------------------------------
    Erlina Hennies
    Deutsche Telekom AG
    ------------------------------


  • 2.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 15, 2019 08:49
    There is no such kind of definition in API itself. It's the design and implementation how you do for the API implementation. With a normal approach, you can require transaction_id in HTTP Header from the client side while it consumes the API. The transaction is generated by client system. Then in the API implementation, you can use the transaction_id and API method, for instance if both of the transaction_id and API method are the same then you can just return the result as the same of the first call.  Certainly  here you need to cache the mapping of the transaction_id, request and result till the full order is completed.

    ------------------------------
    Kevin Kuang
    Hewlett Packard Enterprise
    ------------------------------



  • 3.  RE: ServiceOrderingManagement_POST Idempotency

    Posted Oct 18, 2019 08:51
    Question: does this caching of the transaction_id - you mentioned Kevin - not contradict to the SOA principle of "Service Statelessness" (compare "SOA: Principles of Service Design", by Thomas Erl)?

    Thanks,
    Ralf Hirschbühl
    IABG mbH

    ------------------------------
    Ralf Hirschbühl
    IABG
    ------------------------------



  • 4.  RE: ServiceOrderingManagement_POST Idempotency

    Posted Oct 21, 2019 15:53
    Hi Ralf, 

    The question was not directed to me, but As I voiced in another post, this approach have its merits, and having a cache solution supporting the API calls is an optimization that still maintains the stateless characteristics of the request. Having a "man in the middle" cache is many times a mandatory and widely used approach, especially to overcome "no so well behaved" clients.

    It offloads the processing from the main service engine, anytime a cache hit is found, so the flow basically can reply the same thing without executing the main service logic again. 

    In the end it is a trade-off: Building some sort of intercepting pattern to support caching without hitting the main service execution engine is many times a viable and efficient approach. It does increase the complexity of a service and, but I would not say it harms its stateless behavior.

    Think  it that way: 

    Approach 1: 
    - CREATE service, that does everything synchronously.

    Approach 2: 
    - CREATE service that replies quick but DOES NOT PROVIDE a guarantee that the creation completed. coupled with 
    - READ service that allows to pull the status of the REQUEST accepted in the create phase.

    Approach  1 simpler tom implement, less scalable in practice, 
    Approach 2, a bit more complex, but scales significantly better, and is less vulnerable to repeated calls (or at least they do not degrade the service execution as much as approach 1). That improves availability and response time in many important scenarios.

    In both cases the Stateless characteristics of the service can be maintained.

    ------------------------------
    Raphael do Amaral Raymundo
    Ericsson Inc.
    ------------------------------



  • 5.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 15, 2019 08:49
    That's not what idempotent means...the response is not always guaranteed to be the same. It's about the action at the server side.

    However, if you want an idempotent way of creating one, and only one, resource regardless of how many times the request flows through, use PUT.

    ------------------------------
    Craig Bayley
    Salesforce
    ------------------------------



  • 6.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 15, 2019 08:49
    Hi Erlina,

         POST is not idempotent. PUT, DELETE, GET, HEAD, OPTIONS, TRACE are idempotent.

    Regards
    Meher


    ------------------------------
    Meher Irukoti
    Tata Consultancy Services
    ------------------------------



  • 7.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 15, 2019 08:50
    Hi Erlina

    Hi Erlina

    I believe when you send a POST for a service order, an order is created in the SOM component and shared by COM for any eventual communication (to update the content of the service order, or to cancel the service order if it is not yet delivered, ...), this order will contain one or serveral order items, each order item will carry a service,When a service order is processed completly, it will be archived/removed by the SOM, 
    So the service order can not be idempotent, because each time it will create a new order in the SOM. and all communication with SOM for the same service order, the COM should use the service order id already shared by SOM and by using the PUT operation.

    Hope my answer helps you
    Abdeljalil

    ------------------------------
    Abdeljalil Abataleb
    CGI Info Systems Management Consulting Inc.
    ------------------------------



  • 8.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 16, 2019 03:22
    ​Dear All, 
    So, bottom line is, do not use POST. Instead, use PUT. many thanks your feedback.
    Cheers
    Erlina

    ------------------------------
    Erlina Hennies
    Deutsche Telekom AG
    ------------------------------



  • 9.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 16, 2019 04:08
    Erlina,

    The bottom line is POST is NOT idempotent.  You can't use PUT instead because PUT operates on an existing resource. To create a new item in a resource collection you MUST use POST.  See TMF630 API Design Guidelines section 3 Uniform Contract Operations.

    ------------------------------
    Vance Shipley
    SigScale Global Inc.
    ------------------------------



  • 10.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 17, 2019 03:44
    PUT for object creation is wrong. This operation is used for modification on one existing object. If you see the API definition, the object key is mandatory in the URL.
    See the definition "PUT must be used to completely update a resource identified by its resource URI"

    ------------------------------
    Kevin Kuang
    Hewlett Packard Enterprise
    ------------------------------



  • 11.  RE: ServiceOrderingManagement_POST Idempotency

    Posted Oct 16, 2019 17:51
    Edited by Raphael do Amaral Raymundo Oct 16, 2019 17:54
    Hi Erlina, 

    Firts of all, Well summarized Vance Shipley! That is the essence and the references to TMForum recommendations are excellent. If you are working against APIs based in TMForum that should be your guideline.

    You got many perspectives on this matter so far, and all contribute to a given extent (mostly because we do not quite understand your end goal at this moment). 

    Assuming you are working with Entity manipulation against a system that offers Restful APIs, you should first check the standard in RFC2626 for more details on when to use each HTTP method to manipulate your data elements. That is the more formal approach (but valuable since you get familiar with the idea behind most of the answers you see here).

    When faced with this type of questions, normally the assessment is simple, and based in the following premises:

     - POST will CREATE a new entity with the attributes you sent, and in return, it gives you whatever response you agreed upon and in addition, normally a unique identifier for that entity (usually referred to as ID).
    - PUT and other operations (including PATCH) would normally be used for MODIFYING an existing entity in a collection. they would normally contain an ID right in the input, (as they assume we will take action on a targeted entity uniquely identifiable by ID).

    Assuming you are working under the concepts listed above, if what you are looking for is to reduce the response time, you could work with the somewhat Static or Predictable portion of the response and make it statically mapped from request to response or even cache some segment that may be somewhat constant, based in simple lookup keys. You would still need to keep the elements that vary (the ID for instance) as dynamic elements of the response. 

    The underlying question is: What are you trying to achieve with what you refer to as idempotency? (POST or any CREATE API will not be idempotent anyways). so you probably have other targets. Let us know and I bet you'll receive more preise recommendations from the community.

    Looking from another angle: Assume you have another type of "unique id" for the REQUEST itself (and not for the order), you could make a FAST response pattern that returns an acknowledgment the order has been received but is in process. With that approach you could actually have a POST message, that will not return the ID to you (and that can fail) but that will quickly respond to you that the request have been accepted. You would need to couple that with some sort of GET API and some attribute that would allow you to understand that the entity creation already completed (and would then return the ID to you). 

    That pattern can be useful in scenarios where the requirements to get an ID are too strict and may push the execution time of the post request too far away. In that case it may be better to have a POST returning quicker and a Polling or Call Back mechanism to retrieve the id of the created entity later on. 

    Again, a lot of guessing. Let us know what you want to achieve and we may be able to help more. * This is an area of constant discussions and there is no absolute right approach here, but good judgment on which approach to use according to your application needs.


    ------------------------------
    Raphael do Amaral Raymundo
    Ericsson Inc.
    ------------------------------



  • 12.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Oct 17, 2019 09:27
    ​Hi All,

    thanks for sharing your thoughts. We are using the idempotence in this context where the same value shall be returned when calling a service for multiple time with identical access parameters. So basically we will call a service and at some reason, the service down and a retry to call this very same service will be done. So the response shall not return a new value as if it does not recognise the first call, instead, the same return value is always returned as the very first time it was accessed. Hope it clears. As as Raphael mentioned also already, there is no such right or wrong but putting the context into the right Spec is what is matter when applying this.

    Again, thank you very much indeed for your responses, I do appreciate it. We are good at the moment, it may take some test and result, will keep you updated.
    Take care!
    Best
    Erlina

    ------------------------------
    Erlina Hennies
    Deutsche Telekom AG
    ------------------------------



  • 13.  RE: ServiceOrderingManagement_POST Idempotency

    TM Forum Member
    Posted Nov 18, 2019 14:23
    Very interesting discussion, thanks.
    My view (shortly) - idempotency is a means not an end, you need to decide (and understand) what your requirements are and then tailor your behavior accordingly.

    All - please be aware that there is a dedicated community forum for Open API discussions here:

    https://engage.tmforum.org/communities/community-home/digestviewer?communitykey=d543b8ba-9d3a-4121-85ce-5b68e6c31ce5&tab=digestviewer

    I suggest you join the community and read the posts there, and also post your questions there, it is more likely that Open API experts will be following that community.

    ------------------------------
    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.
    ------------------------------