Written by: Dennis Cox & Joey Boyd
Published: 8 September 2016

Have you ever experienced the frustration of trying to use an unfamiliar microwave oven? I certainly have. All I want to do is warm up my lunch, but I end up having to study the text on several of the buttons to figure out how to make the machine go. Sometimes I even have to start pushing buttons to try to discern which combination will make it start cooking my food.

Why is this so hard? Microwave ovens have been around for decades. Everybody has at least a basic understanding of how they work – the power comes on and your food cooks. The longer the power stays on, the hotter your food gets. Pretty simple. So how does a competent engineer with a master’s degree like me have trouble getting my food to cook? It’s all about the interface. Every model of microwave oven seems to come with its own user interface to access all the whiz-bang features. But if you’re not familiar with the interface, it can be hard to even warm up your lunch.

In software development, it’s very important to have a good Application Programming Interface (API). This API defines how to communicate with your software. It tells other application programmers how to interface with your software. Whether it is a function prototype, a data structure format or a remote procedure call definition, this API defines how to interact with your software. It’s like all the buttons on the microwave oven – it’s what you have to do to make your software "go".

Everyone that has to communicate with your software needs to understand your software’s API. If your software needs to communicate with some other software, you need to understand that API as well. Well-defined APIs can allow software modules to communicate with one another effectively. Enforcing the API as the boundary between software modules can help empower good software design principles such as decoupling and information-hiding.

In a recent blog post, Nathan introduced the Firefly platform. This platform provides an environment where microservices can communicate with the Northbound Interface and with one another to accomplish various functions. This communication involves exchanging REST-like messages over a brokered messaging system. These messages effectively represent the microservice’s API. There can be a lot of communication required between numerous microservices which work together to perform an overall task. All of this communication suggests the importance of representing the interfaces between these microservices: the APIs.

An API needs to effectively define the means by which to fully interact with a microservice. This could involve manipulating configuration data, querying state data, triggering an action and/or recognizing that an event has occurred. This API needs to be both easily parsed by a machine and easily understood by a human. Look to the web and you’ll find several solutions for modeling APIs and in particular those which involve REST-like messages. RAML is an example of this.

We needed to pick an API modeling solution for Firefly. All we needed to do is look to our managed devices to find a method which was already in use and met these criteria. The next generation of ADTRAN network managed devices uses a data modeling language known as YANG. YANG was created by the Internet Engineering Task Force as a means to model configuration data, state data, remote procedure calls and notifications for network management protocols. YANG has been gaining traction in the telecom industry as a modelling language for equipment that supports NETCONF or RESTCONF. The language itself knows nothing of the protocol, but rather serves as a means to define and organize a hierarchy of data including relationships between the data. Defined actions can be specified using remote procedure calls (RPC) definitions and events can be sent using defined notifications. This exactly matched our requirements for modeling the API for a microservice.

YANG also provides a means for defining custom language extensions. We used this feature for modeling how certain data is to be used. For example, the model can use these extensions to specify that portions of data may have restricted access.

Within the Firefly platform, YANG models are used to define and describe a microservice’s API. Microservices that interact with the outside world over the Northbound Interface use these YANG models to inform users of a Firefly product (such as ADTRAN Mosaic Cloud Platform (CP)) about how to make it "go". The models define the API that is provided by the product’s RESTCONF interface. The models also specify other details about the interface, such as what user permissions are required to access a particular resource. Because YANG is a well-defined language, a YANG model could even be parsed by a software utility in order to generate code that helps adapt another software product to the Firefly product.

Microservices that communicate with one another within the platform also get value out of providing a YANG model for their platform-internal interfaces. The model documents what the messages between the microservices should look like. This can help different development teams to write software for their microservices in parallel because the interface has been well-defined. In effect, the YANG model defines a contract between the microservices. The contract stipulates the details of how to talk to a microservice and the details of how it can be expected to respond. This empowers automated testing of the microservices in isolation, with all communication conforming to the contract. Sometimes a scary point in product development is the integration phase -- when you take a bunch of smaller pieces and try to get them to all work together. However, if each microservice has already been tested against a YANG-modeled API, then the developer can have much greater confidence that the integrated set of microservices will be able to communicate with each other. Eventually in a product's life cycle, the API supported by the product will need to change, and YANG can help with that, too. YANG defines a set of rules that, if followed, ensure that model changes are always backwards-compatible. A product that follows the model will have both a backwards-compatible API and a convenient way to communicate with others the changes to that API.

How about an example? Here is a trimmed-down version of the YANG used to specify the Mosaic CP device microservice's API:

module adtran-cloud-platform-devices {
container devices {
adtn-auth-perm:ro-permission read-adtn-cld-pfrm-dev;
adtn-auth-perm:rw-permission modify-adtn-cld-pfrm-dev;

"A Cloud Platform device resource";

list device {
key "device-name";

"A list of devices";

leaf device-name {
type string;
"Unique name of the device";

leaf part-number {
type string;
"The part number (either ADTRAN or other vendor) of the device";

The collection of devices on the system can be retrieved with a GET on a URI like /restconf/adtran-cloud-platform-devices:devices/device which might return the following:

"device-name": "ABC",
"part-number": "1187001G1"
"device-name": "DEF",
"part-number": "1172834G1"

The format of the URI, request body (if applicable), and response body can all be directly inferred from the YANG model definition of the API. This makes it easy to know how to communicate with the device microservice, both from another microservice within Mosaic CP or from a user external to the system. In addition, the necessary permissions to access these devices is specified - a user with the read-adtn-cld-pfrm-dev permission can read the devices; modify-adtn-cld-pfrm-dev is required to create, modify or delete a device.

I have personally found YANG modeling to be a helpful tool in establishing a Firefly microservice’s API. Maybe someday YANG models may even make it easier for me to warm up my lunch.


ADTRAN, Inc. is a leading global provider of networking and communications equipment. ADTRAN’s products enable voice, data, video and Internet communications across a variety of network infrastructures. ADTRAN solutions are currently in use by service providers, private enterprises, government organizations, and millions of individual users worldwide. For more information, please visit www.adtran.com.