Open APIs

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

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

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

Original Message:
Sent: Nov 15, 2022 07:06
From: Jonathan Goldberg
Subject: TMF639 resource endpoints naming convention

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

Hi Jonathan, 

In TMF630, it's stated that IDs are unique identifiers in the context of the application collection with no business meaning. However, in the POST examples of some specifications, there are IDs being specified in the payloads, and I am not talking about IDs of the Referred entities, which are obviously mandatory.
i.e. in TMF 638, there are examples of Service characteristics being posted with an id of "452-gh6", or Features with an id of "Feat1", which doesn't look like technical primary keys, but rather as a user input.
Is this by design or by mistake, and is there a real use case in which the user would enter this information? Hopefully not. :)

Additionally, in TMF632 we have a RelatedParty table with an ID which is a unique identifier of the related entity, and I guess one related entity can be in more than one relationship with another entity, i.e. an organization can be in more than one relationship with a single individual. How do we distinguish between those relationships, I see there is a Role property but not sure if that is a way to go, especially since some of the Ref tables do not have such a property.

------------------------------
Nebojsa Peric
TO BE VERIFIED
------------------------------

Original Message:
Sent: Nov 15, 2022 07:06
From: Jonathan Goldberg
Subject: TMF639 resource endpoints naming convention

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

Hi Nebojsa

Regarding your first point, it's true that in examples across all the Open APIs we have IDs that appear to have business content. That's mainly because examples are created by humans, and we find it easier to create IDs that have meaning. Especially when we want to maintain consistency between multiple examples in the same API.

Regarding your second point, you correctly note that the RelatedParty class has a role property, which is indeed intended for the purpose of defining the nature of the relationship. <Entity>Ref classes will not have a role, since the properties are a strict subset of the the corresponding <Entity> class. If the <Entity>Ref is used in an array where the context may be heterogenous, the API designer is expected to use the Related<Entity>Ref pattern or similar, which would add a role, relationshipType, or similar property.
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.
------------------------------

Original Message:
Sent: Apr 28, 2023 04:58
From: Nebojsa Peric
Subject: TMF639 resource endpoints naming convention

Hi Jonathan,

In TMF630, it's stated that IDs are unique identifiers in the context of the application collection with no business meaning. However, in the POST examples of some specifications, there are IDs being specified in the payloads, and I am not talking about IDs of the Referred entities, which are obviously mandatory.
i.e. in TMF 638, there are examples of Service characteristics being posted with an id of "452-gh6", or Features with an id of "Feat1", which doesn't look like technical primary keys, but rather as a user input.
Is this by design or by mistake, and is there a real use case in which the user would enter this information? Hopefully not. :)

Additionally, in TMF632 we have a RelatedParty table with an ID which is a unique identifier of the related entity, and I guess one related entity can be in more than one relationship with another entity, i.e. an organization can be in more than one relationship with a single individual. How do we distinguish between those relationships, I see there is a Role property but not sure if that is a way to go, especially since some of the Ref tables do not have such a property.

------------------------------
Nebojsa Peric
TO BE VERIFIED
------------------------------


Original Message:
Sent: Nov 15, 2022 07:06
From: Jonathan Goldberg
Subject: TMF639 resource endpoints naming convention

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.

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

​@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
------------------------------

Original Message:
Sent: Nov 16, 2022 01:31
From: Vance Shipley
Subject: TMF639 resource endpoints naming convention

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