The Human API Helps Mailgun Stay Nimble

One of the key ideas in computer engineering is encapsulation. In short, it is removing the unneeded dependencies between unrelated components of a software program.

Dependencies (or references) are easy to accumulate. Their growth stems from inertia, lack of planning and sometimes from laziness. The fewer dependencies you have, the easier and cheaper it is to evolve parts of the product. Dependency-free components are especially pleasant to work with. Consequently, dependency-tangled components are slow and expensive to improve.

But sometimes a dependency is necessary. Products and components do not exist in isolation. They usually talk to each other. This is done via dependencies of a “good kind” called APIs, or Application Programming Interfaces.

In an ideal case, a software product is a collection of independent components that are easy to modify, that talk to each other via small and elegant API.

Mailgun itself was founded to be one of those components, used by developers via an API to control email. We were one of the first companies that embraced the “API as a product” business model. The notable pioneer was Twilio.

But I feel like the power of encapsulation and minimal APIs extends beyond just software.

Large software products can bear an uncanny resemblance to groups of humans – how they grow and evolve and how decisions are made. Minimizing the dependencies between groups of people achieves similar results: more autonomous, independent (and preferably small) teams are usually more productive, can change direction more freely and are able to react to the changing business environments more quickly.

I feel that we could use an API in person-to-person communication, which is why I am a big proponent of having a “human API” to connect different teams. In fact, we have employed this practice since our Mailgun team joined Rackspace.

Our team has remained small and encapsulated so we can tirelessly work to improve our service and add features. At the same time, we are now part of a larger organization and have to interact with a variety of new departments, including human resources, finance, support, marketing and the data centers. To help get each department the information it needs while maintaining a nimble working environment, my co-founder Taylor Wakefield has become the human API.

When a question comes up about Mailgun, it is funneled directly to Taylor. This “call” is then routed to the appropriate person on our team to provide him the information. This keeps our developers from getting bogged down with similar requests (if the question has already been asked before, Taylor can provide the answer) and out of meetings. This allows them to focus on the code.

This system has worked well so far, but I know that having a single endpoint on our API will eventually fail under an increased load. As the needs and the demand continue to grow, it will be important to scale out the API horizontally by adding more people. Ensuring that there is a shared-state, however, is important to prevent “data fighting.” You want to make sure that each particular human API is empowered to make decisions without stepping on the feet of others. At Rackspace, our human resources department does this incredibly well. Rackers are load balanced across the different parts of the business, providing that API to the HR department.

So how can you identify who would make a good human API? If a person finds enough time to explain and document their point of view (and the point of view of the team) in a consistent manner, that person would be an excellent candidate. When a person does this, it demonstrates not only a passion for the product, but also the willingness to connect with others to advance it further.

This requires some discipline too. Sending an email with a question, one performs an API call, almost like sending a message in the “actor” model. When you do this, make sure only “API people” are included in the recipients list. I wish email clients had some kind of “type checking” built-in to prevent the all too common inclusion of unneeded recipients.

And on the receiving end, it helps sometimes to raise an “Unsupported Interface” exception when you find yourself on a list of unrelated (to you) topics. As long as the “human API” idea is shared by everyone in the office, your “exception” will not be misunderstood.

Rack Blogger is our catchall blog byline, subbed in when a Racker author moves on, or used when we publish a guest post. You can email Rack Blogger at



Please enter your comment!
Please enter your name here