Open APIs

  • 1.  Pass by Value rather than reference

    TM Forum Member
    Posted Aug 11, 2021 09:43
    Hello,

    A number of TMF APIs include references to other resources like AppointmentRef or AgreementItemRef. Also related party entities are sent as reference.

    However we would want to pass the entire structure of the referenced resource in some cases. For e.g. in TMF622 we have a number of contact types like Order Contact etc that we may need to include in the payload to a suppler and we would have to pass the information by value as the supplier would have no way of retrieving the entity from the href.

    Is it valid and TMF compliant  to pass resources by value  or is there some other recommended extension mechanism?

    Thanks

    Milind Bhagwat

    ------------------------------
    Milind Bhagwat
    BT Group plc
    ------------------------------


  • 2.  RE: Pass by Value rather than reference

    TM Forum Member
    Posted Aug 12, 2021 02:36
    Hi Milind
    We use the RefOrValue pattern in cases where we believe it is relevant to allow the referred entity to be embedded within the referring entity. Obvious example, ProductRefOrValue is embedded within OrderItem. So as a pattern it is definitely acceptable.
    I think you need to take each case separately and consider why the entity needs to be embedded, and cannot be referred to. For Order, the reason is clear, a new Product does not exist yet in an inventory and so needs to be passed by value when creating the order.
    In your case, I understand the point, but I'm not sure who is calling which operation, can you perhaps clarify this to continue the discussion?

    ------------------------------
    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: Pass by Value rather than reference

    TM Forum Member
    Posted Aug 12, 2021 04:47
    Thanks Jonathan

    This is a use case where an operator orders a product from a supplier or another operator using TMF622. We have to pass a list of different types of contacts  to the supplier or operator. For this we will use Related Party.
    Now these contacts are in our database so we need to pass the contact details by value in TMF 622.  There is no way for the supplier/other operator to retrieve the contact details using href and id.
    Hope this is clear.
    So I am thinking of passing the entire structure of the Party Referred Type under Related Party.

    What do you think?

    Regards

    Milind

    ------------------------------
    Milind Bhagwat
    BT Group plc
    ------------------------------



  • 4.  RE: Pass by Value rather than reference

    TM Forum Member
    Posted Aug 12, 2021 08:23
    I think it's OK, of course you'll have to get your supplier/operator to agree to expose TMF622 with this extension.
    It does raise the more general question of using APIs between organizations, it cannot be assumed that one organization has access to another in order to resolve EntityRefs.
    Interesting discussion.

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



  • 5.  RE: Pass by Value rather than reference

    Posted Sep 25, 2021 04:20
    Hi Milind and Jonathan,

    I believe there can be a potential issue in this approach, because typically some contacts will be common across multiple orders. If you pass all contacts by value, it can lead to an unnecessary duplication in the receiving supplier/operator side, and difficulty in correlating common contacts.

    One solution could be: Your supplier could also expose an API for managing the contacts (TMF 632, 669 or similar). Then you could use this API to sync relevant contacts from your database to theirs.

    Regards,

    ------------------------------
    Sanver Narin
    PiA Bilişim Hizmetleri A.Ş.
    ------------------------------



  • 6.  RE: Pass by Value rather than reference

    TM Forum Member
    Posted Sep 30, 2021 07:15
    Hi Sanver

    You wrote: Your supplier could also expose an API for managing the contacts. In my reply to Milind I pointed out that this may not always be possible.
    To expand this point, it creates a two-way process dependency between the two organizations:

    • BT calls SupplierX to submit the order
    • Now SupplierX must call BT back to get the missing information (to resolve the entity refs)

    Means you need to set up two-way trust relationship (perhaps you have it anyway), and also increases the latency, the load on BT, and perhaps more.
    Certainly can be done like that but needs discussion and cooperation between the involved organizations.



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



  • 7.  RE: Pass by Value rather than reference

    Posted Aug 12, 2021 09:19
    Hello,

    To elaborate on Jonathan's explanations, I found the Part 2 of TMF630 useful about that pattern (Chapter 4. EntityRefOrValue pattern).

    What is not exactly clear to me is if the depth pattern (Chapter 3. Depth and Expand Directive) that leaves it to the client to decide whether he wants nested resources to be passed by Value or Reference is mandatory or not, but that's slightly off-topic.

    ------------------------------
    Lélio RL
    TO BE VERIFIED
    ------------------------------



  • 8.  RE: Pass by Value rather than reference

    TM Forum Member
    Posted Aug 12, 2021 09:30
    Thanks Lélio for the reference.
    To be clear about the depth pattern, it applies to data being retrieved by an API operation call (output), not to data being sent. So this would not help in Milind's use case, where he is invoking an API to send data to another organization.

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