Fast track – From Sonata API definition to running code

by network-devel


As you might (or might not) have heard, MEF has released a developer version of LSO Sonata APIs. Currently, MEF is working on the next version of the APIs that should be available at the end of this year.

Sonata APIs are based on TM Forum APIs which come (for good or bad) with majority of the inherent design decisions of TMF APIs. But that could be a full blog post on its own. Here I would like to walk developers through the process of building code that is compliant with MEF APIs.

Let me start with two assumptions:

  • The reader would like to start building solutions that are compliant with the latest version of Sonata API, which is publicly available here.
  • The reader is prepared (technically and mentally) to read code samples, which, for the sake of argument, come from the Java ecosystem.

If these conditions are met, I promise that at the end of the article the readers will learn how to get a very basic server code up and running. At least for one API endpoint since I plan to use ordering API through this blog post.

Quick start

Sonata SDK contains API structure definitions (Swagger 2.0 format is in use) and specific product descriptors (JsonSchema is in use here). Currently, the structure of Ethernet Virtual Private Line (E-line) and UNI specifications are available.

Dedicated users of Swagger tools will have their preferred code generators to build the client or server code binding for a specific language/framework.

Let’s try to do it in the simplest possible way:

  1. Clone or download Sonata SDK from MEF github
  2. Go to
  3. Copy and paste api/ProductOrder/MEF_api_productOrderManagement_2.0.0.yaml
  4. Generate code bindings project – I have chosen server site code using Spring Framework

Will it work? Well, it depends on the definition of “working.” The process generates all the code bindings for the API, including some basic validations. And, the server code is fully functional – meaning it’s possible to trigger REST requests against it and it will respond with some not very useful payloads:

  • it will complain about sending payloads not aligned with Swagger schema;
  • it will ignore (this might be specific to my implementation) extra attributes that are not recognized.

However, the code has no representation of the MEF specific payloads. How to fix that? Let me explain.

MEF Sonata API vs. TMF API definitions

MEF Sonata APIs are inspired by TMF Open APIs (in our example, the API is based on TMF622). I say that they are inspired as during the MEF standardization process it was discovered that some of the constructs proposed in TMF specification are hard to implement and these were modified. My understanding is that currently MEF is contributing these findings back to TMF.

TMF 622 is an abstract construct that provides a number of ways to manage product orders, but for it  to be useful, it needs to be extended. In reality, the developer must trade specific products. So this is how MEF is building on top of TMF APIs – it adds MEF definitions based on MEF standards to the picture (and modifies TMF constructs where they are not working).

In the TMF world, there are two ways of extending concepts: by implementing characteristic patterns and/or by using extension patterns. MEF is using the latter option to introduce its definitions.

Extension pattern is introduced to support inheritance (one of the core concepts of object-oriented modeling). Basically, a bunch of additional attributes can be introduced to any type represented in API definition, and then add meta-information attributes (e.g. @type, @schemaLocation, @baseType) that say how to interpret these attributes at runtime. Great, right? Well, given the issues we have with the code so far, this is not really helpful. Swagger code generation tools have no idea about these meta-attributes.

Moreover, they are considered as runtime binding concepts. Is there any hope? Well, in the same document we read that “In Swagger 2.0 and 3.0 allOf SHOULD be used to extend an object.” Let’s give it a try.