Open APIs

Expand all | Collapse all

API Extension Sample

  • 1.  API Extension Sample

    TM Forum Member
    Posted 25 days ago
    Hi All,

    I have understood the polymorphic extension pattern. Could someone provide link to developer portal or swagger specifications to see the way TMF Open APIs being implemented in industry. I would like to see practical way of adapting Open APIs.

    Thanks,

    ------------------------------
    Kalpana HV
    Colt Technology Services
    ------------------------------


  • 2.  RE: API Extension Sample

    TM Forum Member
    Posted 23 days ago
    @Jonathan Goldberg could you please help.

    Best Regards, ​​

    ------------------------------
    Kalpana HV
    Colt Technology Services
    ------------------------------



  • 3.  RE: API Extension Sample

    TM Forum Member
    Posted 22 days ago
    The schemas in the TMF APIs don't use specialisation for derived models, i.e. class B inherits from class B, that would simplify the APIs.
    Take e.g. TMF632 where a Party is described as
    Generic Party structure used to define commonalities between sub concepts of Individual and Organization.

     That would suggest that Individual and Organization are specializations of Party. The TMF model looks like this (pseudo-code):
    Party {
      properties: {
        @baseType,
        @schemaLocation,
        @type,
        contactMedium,
        creditRating,
        externalReference,
        href,
        id,
        partyCharacteristic,
        relatedParty​​​,
        taxExemptionCertificate
      }
    }

    Individual {
      properties: {
        @baseType,
        @schemaLocation,
        @type,
        aristocraticTitle,
        birthDate,
        contactMedium,
        countryOfBirth,
        creditRating,
        // skipped some for brevity​​​
        externalReference,
        // skipped some more
        href,
        id,
        partyCharacteristic,
        relatedParty,
        taxExemptionCertificate
      }
    }

    You noticed that the properties in party are a complete subset of the properties in Individual.

    This could also be rewritten like this making it easier for code generators to generate a useful class hierarchy:

    Party {
    discriminator​​: @type,
    required: [ @type],
    properties: {
      ​​@baseType,
        @schemaLocation,
        @type,
        contactMedium,
        creditRating,
        externalReference,
        href,
        id,
        partyCharacteristic,
        relatedParty​​​,
        taxExemptionCertificate
      }
    }

    Individual {
      allOf: [
        {
          $ref: "#/definitions/Party​"
        },
        {
          properties: {
            aristocraticTitle
            // all the other properties that Individual has in addition to the ones from the Party model
        }
      ]
    }

    Now a code generator can create an Individual class that inherits from the Party class. You could also refer to the Party class in the swagger file. Instead of an individual API and an organization API you could just have a party API. The @type attribute​​ would then determine which type it is. 

    For dynamically typed languages, the polymorphism mechanism in the TMF swaggers is probably good enough, for strong-typed languages, not so much. What dos your build process look like?



    ------------------------------
    Martin Goldhahn
    Altibox AS
    ------------------------------



  • 4.  RE: API Extension Sample

    TM Forum Member
    Posted 22 days ago
    Hi Kalpana, Martin
    As perhaps you are aware, the Open API swaggers are generated, using internal tooling, from a consistent set of JSON schemas.
    The schemas are not currently publicly available, but if you had access you would be able to see, for example in Resource Catalog API (TMF634), that we have LogicalResourceSpecification and PhysicalResourceSpecification that are both strict subclasses of ResourceSpecification. The schema files express this by doing
     "allOf": [
      {
        "$ref": "ResourceSpecification.schema.json#ResourceSpecification"
       }
     ]
    much as Martin has described.
    In the swagger generation process, these allOf statements are expanded, meaning that you get all the base class attributes in-line. This is perhaps unfortunate since it means we are missing the provenance of the class structure.
    Take a look also at the examples in the user guide, again for TMF634, you will see how type and baseType are used, e.g.:
    "id": "43",
    "href": "https://mycsp.com:8080/tmf-api/resourceCatalogManagement/resourceSpecification/43",
    "name": "Nokia 7750 SR-s Service Router",
    "description": "This resource specification defines an IP router provided by Nokia",
    "@type": "PhysicalResourceSpecification",
    "@baseType": "ResourceSpecification",
    "@schemaLocation": "https://mycsp.com:8080/tmf-api/schema/Resource/PhysicalResourceSpecification.schema.json",

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



  • 5.  RE: API Extension Sample

    TM Forum Member
    Posted 22 days ago
    Thank you very much @Martin Goldhahn for your kind response. We are implementing TMF Open APIs for the first time. Conceptually we have understood, in most of the cases, polymorphic extension to be used while defining TMF compatible APIs for an organisation. Though, we knew extensions are based on TMF core API specification and design guidelines,  there are thoughts like if each organisation start extending the APIs for its need, it may defeat the purpose of having the industry standard.  So, we hesitate to use polymorphic extension. If we could see working industry examples of TMF open API extension, we could be more confident to implement polymorphic extension.

    Best regards,

    ------------------------------
    Kalpana HV
    Colt Technology Services
    ------------------------------