If you are considering an implementation of a TMF Open API or already started such a project, you may have questions about how best to approach it. Even though you have access to the necessary resources and specifications as a member of TM Forum, you may still be overwhelmed by the number of documents you need to work with. In this article, I share some of my experiences and provide a guide to help you design integration interfaces based on TMF Open API specifications more effectively.

TMF’s promise

One of the primary goals of TMF is to remove technological barriers between service providers, technology suppliers, and systems integrators. More specifically, TMF Open API [2], as one of the TMF digitalization program branches, promises to drive the execution of Communications Service Providers’ digital transformation by providing a widely adopted framework that eliminates obstacles.

The TMF Open API is a set of around fifty API specifications that covers many B/OSS domains and facilitates data exchange within internal systems and between industry partners. The TMF Open API data model is based on the TMF Information Model (SID) and provides a simplified view of it.

My take on TMF Open API

Having implemented several TMF Open APIs and being a part of the TM Forum Community, my perspective on TMF Open API is as follows. TMF Open API specifications are an excellent reference on which to design integration interfaces for exposing capabilities in a standardized programmable manner, making it easier for those who wish to consume them. This is because the specification is inspired by TMF ODA Information Framework (SID) which provides well-defined concepts: Domains, Aggregate Business Entities (ABE), and relationships between them. Additionally, the API information model can aid in problem decomposition, leading to better architecture design.

However, because of the generic nature of the TMF Open API specifications, there are a number of key aspects that you should be aware of and prepared for:

• Every TMF Open API-based integration, whether intra or inter-provider, usually requires a lot of customizations to accommodate real-life use cases. This means that it is highly unlikely that implementations will be interoperable out of the box. The specified TMF Open API operations are not strictly aligned with business processes – they are very generic and mostly consist of CRUD-like operations allowing to operate on the resources organized according to the ‘almost canonical’ information model.
• The TMF Open API entity attribute definitions are also very generic, leaving a lot of room for customization and interpretation. Fortunately, TMF has defined framework extension points to address some of these specifics. Nevertheless, this still requires specific analysis and design to fill any gaps in the API model or to add customized endpoints.
• TMF Open APIs do not provide any standardized service or digital product definitions to support inter-partner operations, such as product ordering. Instead, the specification offers a lot of flexibility and implementation options. While this is great for the ability to use the framework for any kind of things to be served or sold through multiple digital channels, it also means that service models must be defined on a case-by-case basis. This can make each integration a bit more labor-intensive and bespoke to some degree. As a result, following the implementation guidelines does not guarantee seamless, plug-and-play integration.
• Those who have delved deeper into the TMF Open API specifications undoubtedly experienced many issues and shortcomings. For example, the documents often don’t provide enough explanation and examples for API usage in a broader end-to-end context (e.g. call sequence for order capture). Also, it is sometimes not clear how general API guidelines should be applied to a particular API (e.g. which resource query or modify pattern should be used). Furthermore, the maturity of Conformance Profile definitions can vary significantly (e.g. type of operation on the resource is not taken into account), and there are bugs and inconsistencies in spec documents. Combined these can make the implementors’ life harder.
• Regarding TMF Open API Conformance, due to the wide-ranging flexibility defined in the TMF Open API design guidelines document, even full compliance does not guarantee out-of-the-box interoperability with others conforming to the same specification. In addition, there is usually a lot of use-case-specific behavior that needs to be somehow handled. This leads to the conclusion that being TMF Open API compliant (according to the Conformance Profile specification) is of little practical importance.

In my opinion, tailoring the TMF Open API contract to a specific use case context is much more beneficial. Incorporating specifics into customized TMF Open API contracts also makes the interfaces cleaner, easier to implement, and more reliable. As a side effect, this approach also implies that those integration specifics are documented.

A short guide to an effective TMF-inspired API implementation

Regardless of the functional domain, ensuring the interoperability of two systems, especially when they run different and complex business processes, can be a challenging task. Despite the flaws and shortcomings listed in the previous section, it is important to recognize that TMF has conducted a significant amount of research and produced a wealth of materials that can be helpful in this endeavor.

Based on my own experience, here are some general tips for successfully designing TMF-inspired API integration.

• First, choose a set of TMF Open APIs that cover your use case. If you’re not sure which APIs are relevant, you can browse the TMF Open API Table or use documents like GB991 and GB929D to map your use case to a particular domain of the TMF Framework.
• Familiarize yourself with the TMF Open API model and map it to your problem space to ensure implementers on both sides of the integration are speaking the same language. Remember that the TMF Open API model is based on the simplified TMF Information Framework (SID), so studying relevant parts of GB922 specification will give you a better understanding of the domain concepts, entities, and their relationships. The series of IG1163 presentations can also provide you with additional clarifications on the modelling patterns used and guidelines for using model extensions.
• Search the TMF product list, community forum, and TMF Wiki pages for guides on using TMF Open API for your or similar use cases. IG1228 is a good example of such a document, though it only covers a very limited set of use cases. Also, remember that it is always good to work with real partners/systems to test the APIs as you develop them to avoid expensive reworks later on.
• When designing the API contract, narrow it down as closely as possible to the use case context to make the interface more compact and integration-oriented. TMF has defined the mechanisms for extending the model, but you should carefully consider how and where to use them. Also, consider replacing the characteristic’ pattern with concrete schemas and specifying their usage in different business contexts to reduce payload dynamism.
• Review the Open API design guidelines (TMF630) and select the REST API patterns that are most suitable for your implementation. This may include rules for querying, filtering, or referencing resources, updating them, or handling asynchronous calls and notifications. You should also ensure that the entire API space follows the same patterns and governance rules.
• During the implementation, you may need to design products, services, or resources specific to your business domain. In this case, IG1233 will provide you with “Product & Service Modelling Best Practices”. Additionally, when dealing with commercial aspects of tangible or intangible goods being sold, you may also want your product’s offerings or specifications available in the form of a Product Catalogue. For this task, it is essential to be familiar with IG1261, which provides a range of modelling patterns addressing common design problems.
• It is also worth considering use of the standardized product, service, resource, and models that have been developed by other standards bodies such as MEF.

I hope that the above guidelines will help you design clean and well-defined interfaces and make the integration more effective, easy to maintain, and future-proof. In case of any troubles, we will be always happy to help, Just reach out to us!

Bibliography