Open APIs

Expand all | Collapse all

Clarifications on OpenAPI extensions

  • 1.  Clarifications on OpenAPI extensions

    TM Forum Member
    Posted 30 days ago
    hi All,

    The below example is given in TMF630 for the extension of the REST API's using polymorphism.
    PhysicalResource:
    title: PhysicalResource
    type: object
    properties:
    id:
    type: integer
    
    Equipment:
    title: Equipment
    type: object
    allOf:
    - $ref: "#/definitions/PhysicalResource"
    - properties:
    operatingState:
    type: string​


    If i want to add another property as part of the Equipment model which is not a simple type (i.e. its an object or array of objects) then what is the TMF guidance for that.

    i.e.
    property is 'myExtensionRelevantToAllEquipment', This is an array of objects.
    Each element of the array contains an instance of the myExtensionRelevantToAllEquipment which contains propertyA and propertyB which are simple types



    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------


  • 2.  RE: Clarifications on OpenAPI extensions

    TM Forum Member
    Posted 30 days ago
    Hello David

    Did you take a look on Design Guidelines part 2 ? here : https://projects.tmforum.org/wiki/display/API/TMF630+API+Design+Guidelines+4.0.1+R20.0

    You can extend your API using the @type pattern.
    Hope it helps

    Ludovic​

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 3.  RE: Clarifications on OpenAPI extensions

    TM Forum Member
    Posted 27 days ago

    hey @Ludovic Robert,

    Thanks for the response! Yes indeed i have taken a read of the TMF design guidelines part 2 (indeed the above example i pasted is from that document).

    ​I am comfortable that a valid extention of TMF is to use polymorphism to derive from an existing TMF resource and provide your extenion.

    Where i am less comfortable is whether it is valid to create a whole new resource (object) and use it in the API's. As the example only cover adding a single field which is a simple type didnt know if this was allowed.

    so if i do the following the MyExtensionObject itself isnt derived from any TMF resource, is this ok? So i gather @type='MyExtensionObject' but base type cannot be set to anything defined in TMF as this is completely custom.

    PhysicalResource:
    title: PhysicalResource
    type: object
    properties:
    id:
    type: integer
    
    Equipment:
    title: Equipment
    type: object
    allOf:
    - $ref: "#/definitions/PhysicalResource"
    - properties:
    operatingState:
    type: string
    customExtension:
    $ref: '#/components/schemas/MyExtensionObject'
    
    Which points to....
    
    MyExtensionObject:
    title: MyExtensionObject
    type: object
    - properties:
    propertyA:
    type: string
    propertyB:
    type: string



    ​​​

    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 4.  RE: Clarifications on OpenAPI extensions

    TM Forum Member
    Posted 26 days ago
    Hello David
    For me, when you're at resource level, you have to leverage the @type as discriminator to manage the resource 'flavor'. If you use the TMF 'standard' resource then @type  = PhysicalResource, if you have defined your 'own' resource then @type="AlteredPhysicalResource". The API end-point could expose only one of them or both.

    When you defined your specialization "AlteredPhysicalResource" you can extend the TMF resource(as you did) but you can also "restrict" the TMF resource but in order to keep the TMF conformance you must keep TMF mandatory attribute and not redefine the meaning of the TMF attributes re-used.
    ​​​
    Ludovic

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------



  • 5.  RE: Clarifications on OpenAPI extensions

    TM Forum Member
    Posted 25 days ago

    " you can extend the TMF resource(as you did) but you can also "restrict" the TMF resource but in order to keep the TMF conformance you must keep TMF mandatory attribute and not redefine the meaning of the TMF attributes re-used."

    The above is really useful @Ludovic Robert because this is something we were fighting with, Is it valid to remove things from TMF resource. Whilst you mentioned that this is ok when subclassing we feel that for some of the base structures lets say 'Service' there are attributes that we just dont need (optional). We are therefore looking to leave these out from our implementation, would TMF see this as not meeting the minimum requirement because we are making our base more restricted?

    I think if i have understood correctly its fine to add a property to a subclassed resource where its type is an object and that object is something i have invented and doesnt have its root in any TMF resource?



    ------------------------------
    David Whitfield
    TalkTalk Group
    ------------------------------



  • 6.  RE: Clarifications on OpenAPI extensions

    TM Forum Member
    Posted 25 days ago
    Hi David,

    The minimum criteria of most API are actually provided in the Conformance document. You will see that you can drop most of the arrays without being incompatible. When you use the arrays the objects in the arrays will have more strict rules to follow.
    The conformance documents typically have an extra character B in the name of the document.

    Regards

    ------------------------------
    Koen Peeters
    Ciminko Luxembourg
    ------------------------------



  • 7.  RE: Clarifications on OpenAPI extensions

    TM Forum Member
    Posted 24 days ago
    Hello David,
    For me it is fine to add an attribute in any class of your API implementation, for all datatype (object, but fine to add a string, a boolean, etc..) as long as it is not yet defined in the API TMF and you use @type accordingly to indicate that this is a specialized of the TMF class.
    Regarding 'extension by subtraction', I've nothing to add to @Koen Peeters below :)

    Hope it helps
    Ludovic
    ​​

    ------------------------------
    Ludovic Robert
    Orange
    My answer are my own & don't represent necessarily my company or the TMF
    ------------------------------