In our first Microservice Showdown, we addressed the architectural design choices behind the most popular APIs — we covered the strengths and weaknesses inherent in each, and we discussed exactly why making such a choice matters. In this article, the second part of the Microservice Showdown series, we’ll be tackling a more complex topic — the overall development approach. We’ll outline the effects of these choices, and explore real-world examples of their effective implementation.

Which Development Approach Is Best?

Why does it matter how an API is developed? The architecture is clearly important — after all, when building a skyscraper, the most important element is the foundation, the base that will bear all that weight for generations to come. A good skyscraper has to withstand the highest winds, the heaviest rains, and the strongest movements of the Earth.

Any good construction worker will tell you that how you build is just as important as what you build. Take for example the pouring of concrete. When a concrete slab is poured, a huge number of variables come into play — the heat of the exterior, the weight load expected, the water hardness, and the size of stratified rebar all play into the composition of the foundation. Any weakness inherent in the process will make the foundation far weaker than is safe. Likewise, the speed at which the concrete is poured, hardened, and set is just as important as its chemical and structural makeup.

What is true in construction is just as true in API development. While the nature of software development is important, so to is the pace, nature, and speed of development. There are many schools of thought concerning what type of development schedule is most effective, but they can broadly be covered in three general classifications:

• Lean Strategy
• Verbose Development
• Two-Speed IT

Lean Strategy = One Thing Done Expertly

A Lean Strategy is one that constrains resources and focuses development on a well-documented, simple, and attainable present objective. When Lego set out to create their API, they had a very specific and detailed plan. This strategy necessarily included a specific feature set and timeline for development that would limit extensions beyond the original format described.

While some would see this as a negative — a model lacking any development outside strict limitations — in many ways, a lean methodology can be extremely positive. The Lego API has proven powerful enough to drive creative and innovative systems. Take the Brickset API for example — an API that ties into the official Lego API functionality to collate and present data on block combinations, availability, and uses. Or look at the Cubiculus API, a system that creates block set numbers, model numbers, set instructions, and more.

How can such a limited API prove more flexible and powerful than one that is purposely diverse? By limiting the scope of your API and preventing the ever-dreaded feature creep syndrome, you not only save time and resources, you focus efforts on testing and proving your API through every iteration. A simple machine is a better working one — less moving parts means less chance for failure and quicker testing rounds.

The primary question is this — what are the realistic results that can be expected? Harking back to our construction analogy, when creating a foundation you must consider the theoretical maximum loads of future occupants and elements such as tables, chairs, windows, etc. Architects must design for the future — do we expect the building occupancy to double within five years? Do we expect occupancy needs to triple before the need to build a new building becomes too great? If we do, then the foundation must be reinforced to allow for future development. If we don’t anticipate growth, however, then expanding the foundation is a waste of resources and space.

The same is true regarding API development. When developing an API, whether it be Private, Partner, or Public, we must to consider the future needs for what an API could realistically evolve into. If your API is meant to do one thing, and to do it extremely well, then developing an omnibus API with bloated functionality is a waste of resources.

Singular is the core concept of a Lean Strategy. When developing in such a methodology, resources are concentrated, and extraneous features are pushed to the side for the benefit of a singular system. For the Lego API, this resulted in a single, unified API that handled one thing — brick characteristics and uses — and handled that one thing extremely well. Consider what the foundational requirements of your API really are — and design specifically for them.

Verbose Development = A Lot of System, a Lot of Effort

What if we know that our foundation will be quickly outgrown, quickly outstripped? Analyzing realistic results may initiate a serious consideration of future requirements, resulting in a provable need for expansion in the short term.

The simple fact is that in the construction world, it is always more expensive to add on something after the fact than to build in from the beginning. New considerations must be made for plumbing, framing, foundation supports, and more. The same is true of API development. When adding features to an API, considerations must be made to ensure that calls do not overlap, that functionalities work in concert, and that documentation is complete.

Verbose Development, then, is the polar opposite of Lean Strategy. Whereas Lean Strategy focuses on a singular feature or set of features, simplifying the focus for the benefit of the larger product, Verbose Development focuses on a group of feature sets for extensive flexibility and usefulness.

A great example of this is the Google APIs set, which is really a single API split between several different API services for clarity and ease of use. Functionally, these APIs tie into each other as a single service; Google Maps ties into GPS APIs, which tie into search APIs for business locations and services, etc. This represents an extremely verbose API system — the sheer power of the Google API collection is as extensible as it is powerful, and is spread across several desired functionalities.

Note, however, that Verbose Development is not necessarily the development of a single API with monolithic capabilities. Revisiting the construction analogy, we can see that verbose construction isn’t necessarily creating two separate, distinct buildings from the start. What we’re actually discussing is the expansion of the foundation — reinforcing the concrete, adding more electrical and plumbing connections, etc. Constructing two buildings is cost ineffective, and could end up dragging the entire production down. The same is true with Verbose Development when APIs are concerned — the methodology is not advocating for the creation of a monolithic multipurpose API, but rather advocating for the creation of an API that evolves.

The Lego API was designed with very specific needs and applications, and for Lego, that was just fine. For a company like Google, however, that is not a great selling point — Google wants to expand, to create, to evolve, and it can’t do that with a simple system.

The answer then is to develop what you need now while considering what you might need in the future. In a wonderful document on evolving Java-vased APIs, IBM Eclipse architect Jim des Rivières makes a case for evolution by keeping (roughly) to several basic rules:

• Never allow code to invalidate older code used by API clients.
• Make sure new libraries and systems are compatible with systems already in use.
• Assume that all functionality in the API is important to someone.

By keeping these facets in mind, we can begin to approach development in a verbose way — that is, developing for what we think will come while maintaining the needs of today.

This, of course, comes with a cost. While Lean Strategy is simple with quick development cycles, Verbose Development is just that — verbose. Testing is done at every level with each new feature to ensure backwards and cross-compatibility. This means time — and lots of it.

Two-Speed IT = Two Lanes for Two Purposes

The construction world is half theoretical and half physical application — designers are faced with an ever varying set of site conditions, customer desires, and material limitations throughout the course of development. To combat this, architects often resort to simulations to test structural designs and pinpoint variables unknowable from paper blueprints.

This is exactly what Two-Speed IT is all about. A proven technology may be applicable to a project, but as long as developers stick to a single approach, no progress will be made toward creating innovative systems. In the Two-Speed IT approach, the the need for a stable outcome is balanced with the need for experimentation; a development track is set aside for stable technologies, and a second fast-track is provided for the development, implementation, and testing of experimental materials.

This type of development has a large strength in the fact that these two lanes complement each other. A fast track for experimental feature-sets can help push your product to the cutting edge of the IT space, all while allowing a track for proven technologies to create a usable product. This is the core of Two-Speed IT — a single track for fast development, with a prolonged track for complex projects.

Business crucial systems and applications are necessarily checked routinely, and “put through the wringer” of Verbose Development. These systems are the veritable lifeblood of your company — why shouldn’t they be carefully monitored over the long term? These systems are so important that the topic of securing them is an entirely separate and equally important topic in its own right.

There’s a caveat, however — the handling of experimental projects is often directly hampered by the verbose development style. If it takes a full month or three to implement a theoretical bit of code or new methodology, it may be obsolete or even superseded by the time it’s implemented. This is where the “two” in “Two-Speed IT” comes into play — while the core systems are developed in a highly controlled, secure way, a secondary channel is provided for the development of theoretical or experimental systems to flourish.

This gives us the best of both worlds — a secure system of verbose development paired with an experimental sounding board, allowing for both a long-term, proven API, and the presence of various functionalities that have yet to be proven. Great examples are the derivations from the development API for the Sony Xperia. While there is a stable and secure API for implementation of services and systems on the flagship phone, there is a separate channel API that ties into the main functionality for the sole purpose of using the illumination bar on the bottom of the phone. While this seems like a small feature, utilizing the illumination bar can provide for “flashlight” apps, message notifications, traffic alerts, and so much more. Knowing full well that providing access to all the features of the phone could be dangerous, Sony implemented a channel where experimentation can flourish.

Likewise, we can see a larger example with the chrome.experimental.* APIs, which allow for the tagging and development of experimental features for the Chrome browser. Because the execution of code natively in the Chrome browser can be extremely dangerous, creating massive security pitfalls in the general API, the segregation of experimental functionality into “sub-APIs” goes a long way towards allowing innovation and experimentation while maintaining mission critical functionality. This sort of experimentation segregation is a great tool for large companies and startups alike — by ensuring your principal system functionality is secure and effective while allowing for the development of new features, any project development cycle can be accelerated, resulting in a project result greater than the sum of its parts.

How You Build is Just as Important as What You Build

The API industry is growing more complex and speciality-oriented by the day. Choosing how you build your API is as important as figuring out your mindset and general purpose. It is perhaps more important when cost or time is an element that must be controlled, as it so often is with startups and smaller companies. Accordingly, deciding between one of the three approaches detailed above is extremely important, and could mean all the difference in the world. Choose wisely.