Open APIs

 View Only

Best practice for documenting implementations of TMF Open APIs

  • 1.  Best practice for documenting implementations of TMF Open APIs

    Posted Aug 10, 2022 05:17
    Hello All,
    I am looking to solicit opinions on the topic above.

    As a background to this, I have been looking at a provider's use of TMF 622 to provide a B2B ordering interface for a selection of products.

    As you can imagine there are implementation-specific details to be added to the general TMF specification and they have gone about it in a reasonable way but with some consequences.

    Their approach has been to provide a developer page and have specific pages for the products that can be ordered (because there is a good deal to say about the products let alone the APIs to order them).

    Then they produced OpenAPI Spec 3.0 yaml files for the APIs based on the Swagger 2.0 files from the TMF and included the details of end points and sandboxes plus pointers to examples and also the product-specific characteristics. 

    All of which is reasonable, but the end result in effect looks like separate implementations of the ordering API for each product. 
    Also , it has provided the way-in for variations in customisation of the API to creep in as there are multiple API specs.

    So my question simply is does anyone have a good example of a TMF 622 portal for multiple products from a common API?

    Also, I noticed that the MEF in taking TMF 622 for their LSO Sonata Product Ordering API has similarly produced an OAS 3.0 specification in YAML of the ordering API (and also have changed aspects of the model related to identifying related parties and orders in effect creating a different API). The fact that the TMF spec is Swagger 2.0 (in JSON) and these other specifications are OAS  3.0.x (in YAML) makes comparisons for the differences tricky. 

    So any thought to publishing OAS 3.0 specs for the existing published APIs to head off what other people seem to be doing?

    Derrick Evans