Open APIs

 View Only
  • 1.  TMF656 Service Problem Management v4.0.0 | RelatedPlace vs RelatedPlaceRefOrValue

    TM Forum Member
    Posted Aug 25, 2021 21:01
    Edited by Pooja Vakharia Aug 25, 2021 23:09
    Hi There,

    The API user guide resource model for TMF656 Service Problem Management v4.0.0 depicts "affectedLocation" relationship as RelatedPlace sub-resource, but there is no provision to supply "affectedLocation" by values such as street address etc. Would this be better aligned to TMF640 v4.0.0 where the place is referred as a RelatedPlaceRefOrValue sub-resource?

    ------------------------------
    Johnson Drago
    Telstra Corporation
    ------------------------------


  • 2.  RE: TMF656 Service Problem Management v4.0.0 | RelatedPlace vs RelatedPlaceRefOrValue

    TM Forum Member
    Posted Aug 26, 2021 01:49

    Hi,
    That's a good point. I have noticed such differences between APIs as well. We always prefer if the API supports RefOrValue patterns instead of only one of the variants (Ref or Value only).
    So here and there we have already customized the TMF OpenAPIs on our own. Same with RelatedParty by the way, where a RelatedPartyRefOrValue would also make some things easier.

    I am curious if there are plans to unify the APIs.

    Regards,

    Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------



  • 3.  RE: TMF656 Service Problem Management v4.0.0 | RelatedPlace vs RelatedPlaceRefOrValue

    TM Forum Member
    Posted Aug 26, 2021 02:38
    Hi Jan and Johnson

    I remind you that at least for GET, you can use the expand and depth directives on the query param string to include referenced entities by value, even if the schema has only xxxRef. So this whole discussion becomes relevant only when there is a need to pass the value as input (or in the rare cases when you want the value in output of a POST or PATCH).

    As a general guideline we use RefOrValue when we feel that there may be a need to pass the information in by value. Let's take some extreme examples:
    • References from inventory item to catalog item - e.g. Product has a reference to ProductSpecification. Here it is clear that RefOrValue would be not be appropriate. When POSTing a Product you would never provide catalog information by value
    • References from order to inventory item - e.g. ProductOrder has a reference to Product. Here it is clear that RefOrValue is essential, since when the order for a new product (provide) is created or submitted the product will not be in the inventory, so it has to be passed in by value
    In your particular example, I guess that there is a tacit assumption that places affected by the service problem are known places in some GIS or other address management system, and hence there is no need to pass by value, only by ref. If you feel that this is incorrect, feel free to submit CRs for those particular areas where RefOrValue is needed.

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



  • 4.  RE: TMF656 Service Problem Management v4.0.0 | RelatedPlace vs RelatedPlaceRefOrValue

    TM Forum Member
    Posted Aug 27, 2021 03:45

    Hi Jonathan,
    I am aware of the possibility via Depth. In our case the problem is rather that we want to introduce a certain API and then by the exclusive use of an EntityRef pattern (e.g.: RelatedParty, RelatedPlace) there are so many dependencies to further TMF OpenAPIs (who provides now Party Mgmt API, GeographicSite API etc.) that we get more or less into a "deadlock". It can make it difficult for Telcos to slowly transform forward to TMF based interfaces.

    This is the reason why we adjust our APIs here and there to allow RefOrValue. We then prepare the applications to be able to do both: Reading the entity by value or retrieving information from the entity using a HREF if needed.

    Regards,

    Jan



    ------------------------------
    Jan Lemmermann
    OSS Lead Architect
    EWE TEL GmbH
    ------------------------------