Open APIs

 View Only
  • 1.  TMF639 - Resource Inventory - Patterns for schema definition for different resource types

    Posted Dec 09, 2019 10:00

    Hi All,

    I work for a UK Energy Company (SSE) and we are using the TMForum Open APIs to define a business service API layer across a number of legacy applications.  We are early on in our TMF journey and we are trying to map Resource Inventory to our landscape.

    What we have found is that Resource along with Service are generic APIs that are intended to be used to interact with many different types of Resources and Services - obviously those resources and services will require different data fields to describe them accurately.

    The latest definition of the Resource Inventory API provides operations for
    Logical Resources
    Physical Resources
    and a catch all that allows you to specify the type of resource you want to retrieve
    GET /{resource-type}/{id}

    What I'm not clear on is the TMF pattern for specifying the schema that will be returned for each individual resource.
    In a GET Resource scenario

    1. Would I use a supeset schema that specifies all the fields across all different resources and just populate the ones specific to the resource I am dealing with - so regadless of the type of resource return the API consumer the same schema

    2. Or would I define specific schemas for each resource, and use the schema that is aligned to the resource type - so the schema and data returned is specific to the type of resource requested (i.e. Meter, or InHome Display, or Registration for example)

    3. Oris it OK to extend the out of the box resource inventory API to add resource specific operations, that use schema for that particular resource. i.e.
    GET /ResourceInventory/meter/{id} (returns a specific MeterResource structure)
    GET /ResourceInventory/InHomeDisplay/{id} (returns a specific InHomeDisplay structure)
    GET /ResourceInventory/EnergyRegistration/{id} (returns a specific EnergyRegistration structure)

    It gets even tricker on a POST when creating the resources - I want to be able to expose a strongly types schema to the API consumer so that it is obvious what needs to be populated when creating a resource


    Can someone help me on the general pattern that should be used?

    Thanks

    Darryl



    ------------------------------
    Darryl Cook
    SSE Energy Services Ltd
    ------------------------------


  • 2.  RE: TMF639 - Resource Inventory - Patterns for schema definition for different resource types

    TM Forum Member
    Posted Dec 09, 2019 10:23
    Hi Darryl

    Welcome to the world of TMF Open APIs - it's great to see involvement from additional industries and lines of business.
    Specifically for your query on Resource - I can refer you to @Thomas Braun of Deutsche Telekom, who is leading the work on the Resource Inventory API​.

    More generally, most of the entity definitions in the Open API model include extensibility fields @type , @schemaLocation, and @baseType - the schemaLocation would point to a parseable schema (likely JSON schema) that would specify the extensions to the entity model that you choose to make.
    The use of these fields is described in the Guidelines documents at https://projects.tmforum.org/wiki/display/PUB/TMF630+API+Design+Guidelines+3.0+R17.5.1 - worth taking a look at these if you are not familiar with the Open API design patterns and guidelines.

    However - entities such as Resource, Service, and others are driven by the Specification/Instance model, so that a Resource in the inventory (for example) is defined by a catalog definition in the corresponding ResourceSpecification, which lays down the characteristics and relationships for the instantiated Resource. To take a highly simplified example, let's suppose you have a resource defining a virtual storage medium, with a characteristics volumeSize and storageType. A fragment of the JSON for a resource ​​​instance might appear either as (dynamic catalog-driven):
    {
        "characteristic": [
             {
                 "name": "volumeSize",
                 "valueType": "string",
                 "value": "50GB"
             },
             {
                 "name": "storageType",
                 "valueType": "string",
                 "value": "SSD"
             }
        ]
    }

    or (strongly-typed):
    {
         "volumeSize": "50GB",
         "storageType":"SSD"
    }

    There are advantages and disadvantages in both representations, and you need to consider what works for you (and your consumers).

    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 Inventory - Patterns for schema definition for different resource types

    TM Forum Member
    Posted Dec 11, 2019 01:09
    Edited by Vance Shipley Dec 11, 2019 01:10
    Darryl,

    Your starting point should be the creation of a collection of Resource Specifications (TMF634) which describe the Resources you will instantiate within your Resource Inventory (TMF639). For example:

    POST /resourceCatalogManagement/resourceSpecification/
    Content-Type: application/json
    
    {
         "name": "Electricity Meter",
         "description": "This resource specification defines an Electricity Meter", 
         ...
         "resourceSpecCharacteristic": [
              {
                   "name": "Manufacturer Model",
                   "valueType": "string",
                   "resourceSpecCharacteristicValue": [
                        {
                             "valueType": "string",
                             "value": "Sangamo K2A"
                        },
                        {
                             "valueType": "string",
                             "value": "Arch Meter SW3005"
                        },
                        ...
                   ]
              },
              ...
         ]
    }

    Now when you create an instance in your Resource Inventory (TMF639) you provide the Resource Specification used and the Characteristic values as allowed by the specification:
    POST /resourceInventoryManagement/resource/
    Content-Type: application/json
    
    {
         ...
         "resourceSpecification": {
              "id": "42",
              "href": "/resourceCatalogManagement/resourceSpecification/42",
              "name": "Electricity Meter"
         },
         "resourceCharacteristic": [
              {
                   "name": "Manufacturer Model",
                   "value": "Sangamo K2A"
              },
              ...
         ]
    }​


    There are no special schemas needed to define profiles of resources with the list of possible characteristics and allowed values, value ranges or value types.

    If however you want to go beyond this mechanism you may use polymorphism to define new classes. You would provide a schema which extends an existing class (i.e. LogicalResource) and may add attributes not defined in TM Forum Open APIs.

    {
         ...
         "@type": "ElectricityMeterSpecification",
         "@baseType": "PhysicalResourceSpecification",
         "@schemaLocation": "/resourceCatalogManagement/schemas/ElectricityMeterSpecification"
         ...
         "myAttributeSpecification": {
         ...
         }
    }

    {
         ...
         "@type": "ElectricityMeter",
         "@baseType": "PhysicalResource",
         "@schemaLocation": "resourceInventoryManagement/schemas/ElectricityMeter"
         ...
         "myAttribute": {
         ...
         }
    }​


    I would encourage you to take the ResourceSpecification/Resource, CharacteristicSpecification/Characteristic pattern as far as you can before resorting to polymorphism.



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



  • 4.  RE: TMF639 - Resource Inventory - Patterns for schema definition for different resource types

    TM Forum Member
    Posted Feb 25, 2020 13:03
    Hello Vance,

    you wrote "There are no special schemas needed to define profiles of resources with the list of possible characteristics and allowed values, value ranges or value types."

    Shure, there is no need to do this. But if I want?
    What is the meening of TargetResourceSchema sub-resource?  My assuption is, that you can reference a schema which describes allowed Characteristics and their types.
    Do you have any information regarding TargetResourceSchema , TargetServiceSchema or TargetProductSchama?
     
    Thanks and best Regards
    Niels Prusas
    Deutsche Telekom IT GmbH



    ------------------------------
    Niels Prusas
    Deutsche Telekom AG
    ------------------------------



  • 5.  RE: TMF639 - Resource Inventory - Patterns for schema definition for different resource types

    TM Forum Member
    Posted Feb 26, 2020 03:14
    The use of. Polymorphism is described in TMF630 REST API Design Guidelines; Part 2.

    If you want to use polymorphism to have more strict data types you would again create ResourceSpecifications in a resource catalog but first you would create new schema and reference same in "@type" and "@schemaLocation" attributes:

    POST /resourceCatalogManagement/resourceSpecification/
    Content-Type: application/json
    
    {
         "name": "Electricity Meter",
         "description": "This resource specification defines an Electricity Meter",
         ...
         "@type": "ElectricityMeterSpecification",
         "@schemaLocation": "/resourceCatalogManagement/schema/ElectricityMeterSpecification",
         "@baseType": "ResourceSpecification",
         "targetResourceSchema": {
              "@type": "ElectricityMeter",
              "@schemaLocation": "/resourceInventoryManagement/schema/ElectricityMeter"
         },
         ...
    }
     


    The attribute targetReourceSchema of ResourceSpecification is defined in TMF634 Resource Catalog API:
    targetReourceSchema
    A target resource schema reference (TargetResourceSchemaRef). The reference object to the schema and type of target resource which is described by resource specification.

    When you are instantiating in your resource inventory (TMF639) you will also use the polymorphiic types:
    POST /resourceInventoryManagement/resource/
    Content-Type: application/json
    
    {
         ...
         "resourceSpecification": {
              "id": "42",
              "href": "/resourceCatalogManagement/resourceSpecification/42",
              "name": "Electricity Meter",
              "@type": "ElectricityMeterSpecification",
              "@schemaLocation": "/resourceCatalogManagement/schema/ElectricityMeterSpecification",
              "@baseType": "ResourceSpecification"
         },
         ...
    }​




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