Open APIs

 View Only
  • 1.  TMF639 resource endpoints naming convention

    Posted 21 days ago
    Hi Team,

    The TMF639 indicates three main generic endpoints /resource, /physicalResource, /logicalResource. As far I know they are mapped to specific "@baseType" attribute while "@type" indicates particular class of the resource e.g. Port, MSISDN, Connection.

    I had a look at the examples in TMF639 and it looks like that all type of ​resources​ can be managed through the endpoints which I have listed above. If this is the true then it has implications that resource id has to be unique across all resource types. Am I correct with that?

    On the other hand since this is REST API maybe the resource type should be included in the endpoint URL e.g.:
    • port resources management - /resource/port ,
    • msisd resource management - /resource/msisdn.
    If this is true then do we need to expose these generic endpoints as well?

    ------------------------------
    Sebastian Wawrzyniak
    Sonalake
    ------------------------------


  • 2.  RE: TMF639 resource endpoints naming convention

    TM Forum Member
    Posted 20 days ago
    Hi Sebastian
    You raise an interesting point here. But first please note that IDs in the TMF Open API are technical primary keys with no business meaning (please refer to TMF630 design guidelines). The value of a logical resource such as MSISDN, IP Address, etc. is in the value attribute. There is no constraint that value must be unique across all resource types.
    Having said that, the ID uniqueness of any Open API entity (not just Resource) is predicated on there being a single source provider of the API, so that the IDs can be generated uniquely across the entity class and that the retrieve can be unique.
    There can be multiple reasons why there might not be in practice a single provider:
    • Sharding the same entity class across multiple physical deployments (e.g. due to size of data store or for geographic adjacency in large countries)
    • Federation across multiple class subtypes (Resource inventory is a good example here)
    In such cases, we might expect an intermediary component to take responsibility for:
    • "massaging" IDs to be unique by e.g. appending source system to ID from native system
    • routing GET retrieve, PATCH and DELETE requests to the correct system
    • federating and GET search requests across multiple systems and collating the results
    An alternative approach, at least for the federation by subtypes, would be to create concrete subclasses for each subtype and route the endpoints to the correct system according to the concrete subclass

    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: TMF639 resource endpoints naming convention

    TM Forum Member
    Posted 20 days ago
    Edited by Ascendon Commerce 20 days ago
    @Jonathan Goldberg Would it be ok from a TM Forum compliance point of view, to support only URLs specific to resource specification (logical or physical) and NOT support the generic resourceSpecification?

    So support only:
    /resoureCatalog/logicalResourceSpecification​
    /resoureCatalog/physicalResourceSpecification​

    And NOT support generic:
    /resoureCatalog/resourceSpecification​

    Since the CTK for TMF634 uses the generic URL to validate conformance, will this be a problem?

    ------------------------------
    Ascendon Commerce
    Microsoft Corporation
    ------------------------------



  • 4.  RE: TMF639 resource endpoints naming convention

    TM Forum Member
    Posted 20 days ago
    Edited by Vance Shipley 20 days ago
    On Nov 15, 2022 06:05 @Sebastian Wawrzyniak​ wrote:
    > The TMF639 indicates three main generic endpoints /resource, /physicalResource, /logicalResource. As far I know they are mapped to specific "@baseType" attribute

    The main resource path is /resource, the others are optional and, IMHO, should be avoided. At least do not feel compelled to use them.

    > while "@type" indicates particular class of the resource e.g. Port, MSISDN, Connection.

    It does only if you are designing a solution which is heavy on the use of polymorphism. This is not necessary, the starting point is the use of ResourceSopecifications for runtime modeling. Creating new types is a design time solution which has it's benefits but it's disadvantages include not being extensible at runtime.

    > On the other hand since this is REST API maybe the resource type should be included in the endpoint URL e.g.:
    • port resources management - /resource/port ,
    • msisd resource management - /resource/msisdn.
    Please don't do that! 

    ------------------------------
    Vance Shipley
    SigScale
    ------------------------------


  • 5.  RE: TMF639 resource endpoints naming convention

    Posted 20 days ago
    @Jonathan Goldberg @Vance Shipley
    thanks for your comments they make a lot of sense for me

    To sum up:
    • service should expose single /resource endpoint. That endpoint should be used for CRUD operations on any resource type. If needed the call can be federated to 3rd party systems.
    • the service has to guarantee the technical id uniqueness so the GET/PATCH/DELETE operation can work
    • the resource type should be defined through the resource specification (in resource catalogue) rather then through the polymorphism



    ------------------------------
    Sebastian Wawrzyniak
    Sonalake
    ------------------------------