Open APIs

Hello.
This is a multipart question.
1. If an API resource has several relations with another resources, f.e. ResourceSpecification and Party. ResourceSpecification contains array of PartyRoleRef, with an uniquie ID of a Party.

1. How to remove a specific reference to a Party? I cannot delete it by URI, because the ID relates to the Party, but not to the reference.
2. If I patch the ResourceSpecification and provide an array of RelatedPartyRefs whout the RelatedPartyRef I want to remove - should I specify all attributes of other RelatedPartyRefs, or IDs only?

2. In "TMF634 Resource Catalog Management API REST​ Specification" ResourceSpecification can have 0..* ResourceSpecCharacte​ristics. However, ResourceSpecCharacteristic doesn't have any keys. 

1. How can I address a specific ResourceSpecCharacteristic via GET? I expected something like GET /ResourceSpecification/123/resourceSpecCharacteristic/456, but RSC doesn't have any IDs.
2. According to resource model of the API, ResourceSpecCharacteristic instance belongs to a specific instance of ResourceSpecification. It means that if I want to have same characteristic in different specifications, I have to redefine such characteristic for every specification. For example, "operating system" characteristic can present in many specifications - for mobile phones, routers, VDS, etc. But, I need to be able specify different set of values in different specification for this characteristic. What entity types should I choose to achieve this?

------------------------------
Sergey Gusev
Mobile TeleSystems OJSC
------------------------------

Hi Sergey

For your first questions - please see the published design guidelines (at https://www.tmforum.org/resources/standard/tmf630-api-design-guidelines-3-0-r17-5-0/), where there is an extensive discussion on how to manipulate sub-resources that are arrays. Example 2 in the document is probably what you are looking for.

For your second question:

• in the current API model there is no ID field in Characteristic (everywhere, whether product, resource, etc). - the key is the name attribute. Personally, I would prefer to have also an explicit ID field in Characteristic, this seems to me to be more robust, and it is thus in the SID. This is perhaps something that we can suggest as part of release 18.5. But in any case the API design guidelines do not currently prescribe a common way to directly access sub-entities. In a recent face-to-face meeting a similar issue was raised, but I don't think that any concrete decision was made.
• please be aware that the API resource model (as reflected in the spec documents and UML diagrams) is not an underlying implementation model (as distinct from the SID). The API model is intended to reflect the structure of the resource as input and output in the REST operations. And so the child entities will always appear as contained (solid diamond - UML composition) within the main entity of the API. In your underlying implementation, you can certainly choose to share the same characteristic spec with multiple entity specs (in your case the same ResourceCharacteristicSpec could indeed be used by multiple ResourceSpecifications).

Hope it helps

------------------------------
Jonathan Goldberg
Amdocs Management Limited
------------------------------

Original Message:
Sent: Jul 10, 2018 10:25
From: Sergey Gusev
Subject: PATCH, arrays and characteristic/value objects

Hello.
This is a multipart question.
1. If an API resource has several relations with another resources, f.e. ResourceSpecification and Party. ResourceSpecification contains array of PartyRoleRef, with an uniquie ID of a Party.

1. How to remove a specific reference to a Party? I cannot delete it by URI, because the ID relates to the Party, but not to the reference.
2. If I patch the ResourceSpecification and provide an array of RelatedPartyRefs whout the RelatedPartyRef I want to remove - should I specify all attributes of other RelatedPartyRefs, or IDs only?

2. In "TMF634 Resource Catalog Management API REST​ Specification" ResourceSpecification can have 0..* ResourceSpecCharacte​ristics. However, ResourceSpecCharacteristic doesn't have any keys.

1. How can I address a specific ResourceSpecCharacteristic via GET? I expected something like GET /ResourceSpecification/123/resourceSpecCharacteristic/456, but RSC doesn't have any IDs.
2. According to resource model of the API, ResourceSpecCharacteristic instance belongs to a specific instance of ResourceSpecification. It means that if I want to have same characteristic in different specifications, I have to redefine such characteristic for every specification. For example, "operating system" characteristic can present in many specifications - for mobile phones, routers, VDS, etc. But, I need to be able specify different set of values in different specification for this characteristic. What entity types should I choose to achieve this?

------------------------------
Sergey Gusev
Mobile TeleSystems OJSC
------------------------------