The art of providing an API is extremely interesting, largely due to the dichotomy of opposing requirements. On the one hand, an API must be innovative, quick to change, and ever evolving. On the other, consumers demand stability, and with it, the security that comes with proven solutions.

The constant battle between old and new, centralized and distributed, has led to a unique range of solutions and approaches to solving the dilemma. One such solution is the concept of microservice gardening, the idea of being a “landscaper” for an API-first platform or suite of microservices. Microservice gardeners must use innovative techniques that embrace a distributed architecture, avoiding the Kafkaesque monolith at all costs.

In this piece, we’re going to discuss what it means to be a “microservice gardener”, and present six ways API providers can excel as masters.

What Is an API Gardner?

“Companies are increasingly restructuring themselves into something that has organizational boundaries that have technical alignments…what you’re doing is also aligned with how you’re doing it. Then it’s easier for you to restructure and rebuild yourself when you have to.”

Imagine a garden — a range of flowers, each with their own needs and purposes. This is the API microservice landscape. Just as each flower or vegetable needs specific fertilization and specialized care, it is the role of the provider to give attentive care to API microservice consumers as an API gardner.

As a landscape manager, it is your duty to control and augment the environment to allow for the greatest growth and prosperity. Within an API landscape, not supporting users where they are can choke your system and any potential user base you have yet to develop. Failing to do so does not just hurt the environment, it could possibly destroy it.

These issues arise from a fundamental shift in how APIs are produced and managed. Whereas APIs used to be monolithic and shackled to larger systems, we are now in an era of microservices, all designed to do specific things in concert with other solutions, which forces a containerization and decentralization of the API model.

6 Ways to Become a Master Microservice Gardener

Now that we know what microservice gardening is, let’s look at some techniques we can apply to master this art.

1) Use Bimodal IT to Avoid Stagnation

“Imagine that you have the castle, which is your legacy system. Now you have these new things coming around where people say ‘oh we should do microservices, and it will be fast, and we can do interesting things.’ They’re highly enthusiastic at what they’re doing, but they also need guidance.”

Bimodal IT is the concept of dealing with disparate styles of work that nonetheless function perfectly well separate from one another. “Bimodal” means two modes, and in this case, the term matches the function — one focused directly on predictability, and the other on exploration.

The exploratory type focuses on unique and innovative solutions that result in a requirement to explore rather than to depend on known, constant functionality. The second development track is the inverse, a dependable codebase that is known, proven, and well documented, thus resulting in predictable results.

While an API provider could simply direct their API to only support one of these types of content and the resultant users through the effect of eschewing innovative, unproven solutions, developers would be excising a large portion of their potential power and user base by doing so. Bimodal IT approaches are designed to support both concepts and approaches. By combining predictable product evolution and documentation with innovation and exploratory tools, developers can harness the “best of both worlds.”

2) Avoid the Kafkaesque Monolith

Erik provides a very good example of what a centralized monolith results in by example of The Castle, a novel by Franz Kafka. Throughout the events of The Castle, the protagonist, known only as K., suffers the tribulations of bureaucracy from a government which erroneously called him into their village for a job that was non-existent.

To Wilde, monolithic architecture is similar to the nightmarish bureaucracy of Franz Kafka’s The Castle

Redirected from contact to contact, ignored by higher-ups with the simple instruction to talk to their subordinates, and never given explanation for any action of the officials, K. exposes the bureaucratic nonsense of the village surrounding the castle, much to the villagers’ chagrin.

Poorly designed and implemented APIs (and even the well designed and implemented ones) sometimes result in this sort of behavior. The user, attempting to use the API for whatever function they deem, are lost in the structure of subordination and redirection. The API design methodology used can somewhat augment this, but giving APIs too much structure could end in a bureaucratic result.

It doesn’t have to be this way, of course. APIs need structure, but just as important as structure is the need for guidance. Designing an API to not only get the job done, but to get it done in an understandable way while allowing for innovation and explorability is a key tenant of bimodal IT. Essentially, you’re joining the old — that is, the bureaucratic — with the new.

3) Design In a Way That Promotes Further Iteration

First and foremost, consider that all of these issues, even those in The Castle, derive from the principle foundations upon which the system is built. No single API specification, documentation, and design approach is perfect, and as such, avoiding dependence on a single monolithic solution will do a lot to resolve this.

When developing an API, keep in mind not only the intended functionality, but the ability to extend that functionality. If an API is designed to perfectly fit only the current requirements, it will be a perfect API — but only for a moment in time.

This is much more of a “top level” concept, but it’s one that needs to be adopted as a mantra for any API provider. When considering an API, don’t think about what the user today wants, or even what the user a year from now will want — future proofing is difficult as technology fluctuates so rapidly. Rather, Wilde recommends the best solution is not to code the functions you expect to need in the future, but to enable the easy additions of those features to an extensible code base. Allowing further functionality through extensible classes and hooks to combine functions creates powerful, longevity-driven solutions.

4) Harvest Concepts and Incorporate

Harvesting and introducing new concepts should be easy. In The Castle, K. not only runs into confusion, he also encounters people actively resisting his attempts to resolve the confusion. Your API should not do this.

Part of a solution is simply allowing your API to be explorable. Don’t lock everything down via obfuscation and layers of haze — explain how an API does what it does, how this can be extended, and how to call this functionality.

Essentially, it should be easy to identify what an API does and to use it for new purposes — failing to provide a system to do this kills any innovation. This has been seen time and time again, and is a prime reason open source has been as successful as it has been. A locked down ecosystem works perfectly — but only if everything is kept internal.

5) Distribute the Seeds: Adopt True Microservices Arrangement

The greatest way to become a master microservice gardener is to move away from centralization. Give teams of developers more autonomy in how solutions are developed and implemented, and allow for greater service discovery on the user side. Essentially, move away from a centralized API approach and more towards a true microservice arrangement.

Developers have the tendency to thinks of themselves as the “central authority”. The developer has made the code, has restricted it, has documented it, and by this process, has complete control. While this is fine for single use APIs or small teams, this is not how an interactive API platform should function. When a provider functions this way, they are being despotic — and with despotism comes inefficiency and bureaucracy.

Instead, approach API development as a benevolent democratic leader. Allow for more personal use, and do everything you can to support growth and understanding. If a gardener cuts too close to the root, they can kill a flower — if a provider does not provide any amount of support for anything other than their specific user case, they’ll do the same to the API.

6) Prune the Service Surface

When it comes down to it, what truly matters to the microservice consumer is the surface of the service. The surface is unique to each offering, but may consist of varying degrees of public developer portals, API metadata, documentations, or other functional summaries and integration methodologies.

While it’s tempting to take the advice here and reveal the entirety of your API, that’s a bit too far in the wrong direction. Consider the simplicity of offering a service surface and making well-defined concepts that are fundamentally shallow in their functionality. By doing this, you’re creating an extensible solution while mitigating the potential damage of innovation for innovation’s sake.

Nurture API Ecosystem Growth

“Instead of having a top-down process to design and document and describe APIs, use more of an ecosystem-like approach… Try to build things in such a way that you make the conditions under which good things will happen.”

As providers and developers create API ecosystems, they need to have a sea change in concept. To do so, API providers must eschew centralization in favor of innovation and new developments.

The best a developer can hope for is this — create a system in which the API is understood and extensible, and from there, create the conditions for success. Even if that success does not immediately happen, preparing should mitigate those possible issues while magnifying the potential for success.