NEW BOOK!
Explore a better way to work – one that promises more calm, clarity, and creativity.

The Human API Manifesto

The Bezos Mandate

In 2002, Amazon founder and CEO Jeff Bezos sent a mandate to his employees that has since become legendary in IT circles. It reads as follows:

  1. All teams will henceforth expose their data and functionality through service interfaces.
  2. Teams must communicate with each other through these interfaces.
  3. There will be no other form of interprocess communication allowed: no direct linking, no direct reads of another team’s data store, no shared-memory model, no back-doors whatsoever. The only communication allowed is via service interface calls over the network.
  4. It doesn’t matter what technology they use. HTTP, Corba, Pubsub, custom protocols — doesn’t matter.
  5. All service interfaces, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to developers in the outside world. No exceptions.
  6. Anyone who doesn’t do this will be fired.
  7. Thank you; have a nice day!

This directive, which some informally call Bezos’s “API Manifesto,” transformed Amazon.

To be sure, transitioning to these formal APIs made life harder in the short term for its engineers. It was also expensive, both in terms of the money spent to develop the new interfaces, and the time lost that could have been dedicated to projects producing immediate revenue.

But once the company embraced Bezos’s mandate, it was able to operate its systems much more efficiently. It also enabled the launch of the public-facing Amazon Web Services, which now produces a much needed influx of profit, and allowed Amazon’s web store to easily expand to encompass outside merchants, a key piece in their retail strategy.

The impact of the API Manifesto has since expanded to the IT industry as a whole. From start-ups to massive organizations, the idea that information systems are more valuable when interacting through clearly specified and well supported API’s has become common.

Last week, for example, the cofounder of an IT firm told me the story of how he helped a large financial services firm implement an API for a set of services that were previously accessed in an ad hoc manner  (think: batched FTP).

It cost the firm a little over a million dollars to make this transition. He estimates it now helps them earn an additional $100 million in revenue each year through a combination of cost savings and the new customer acquisition applications enabled by providing a clearly specified and accessible interface for these services.

On Attention Capital

When I heard about the API manifesto, a provocative thought popped into my head: could these same underlying ideas apply to communication between people?

To provide some background to this question, let me first remind readers that my attention capital theory argues that the most valuable capital resource in a knowledge work organization is the brains of its employees. Or, to be more specific, the capacity of these brains to focus on information, process it through neurons, and then output more valuable information.

Success in knowledge work is about getting the best possible return on this attention capital, much as success in the industrial sector is about getting the best possible return from physical capital (factory equipment, trucks, shipping containers, etc.).

I believe that many knowledge work organizations currently get sub-standard returns on their attention capital because the workflows they deploy — which are often unspecified and emerged haphazardly  — depend too heavily on constant, unstructured communication, which conflicts with the way the human brain operates, reducing these brains’ capacity to think deeply and produce valuable output.

The natural follow up question to this observation is to ask what work would look like without constant unstructured messaging. It’s this follow-up question that brings me back to APIs…

The Human API Manifesto

Imagine if a Jeff Bezos figure at a major knowledge work firm sent a mandate to his or her employees that read something like this:

  1. Our work will be seen as a collection of processes that take in specific inputs and produce specific outputs. Individuals are associated with the processes that they support.
  2. Each process has well-defined and well-documentated communication protocols specifying how information comes into the process and how it leaves. It also has protocols specifying how the individuals associated with the process internally coordinate, including when and how this coordination occurs. We call these protocols human APIs (hAPIs).
  3. There will be no other form of inter-personal communication allowed: no generic email inbox or instant messenger channel that can be used for any purpose, and no casually dropping by someone’s office to make a request. The only communication is through hAPIs.
  4. Different hAPI specifications will include different technologies. Some will include no technologies at all. The details of the tools used to implement these protocols are less important than the protocols themselves.
  5. If a particular request or notification seems too minor to justify its own process, or hAPI within an existing process, consider eliminating it. The need to specify hAPIs will help our organization focus more relentlessly on activities that create real value, and help eliminate minor asks that are convenient in the moment, but end up reducing the return on our attention capital in the long term.
  6. Anyone who doesn’t do this will be fired.
  7. Thank you; have a nice day!

Brilliant or Blunder?

A mandate like this would either turn out brilliant or a colossal blunder, which is exactly why it intrigues me.

The arguments in favor of this being brilliant include the observation that well-crafted protocols can minimize the cognitive overhead required to keep track of the different projects and tasks on your plate. Instead of drowning in an ever-filling pool of messages, you can instead work to satisfy a clear set of expectations and optimized action.

The structured nature of this communication also eliminates the requirement to constantly monitor general-purpose communication channels, which helps minimize attention residue — generating a non-trivial boost in your cognitive capacity. As I argued in Deep Work, if you can avoid constant “quick checks” of inboxes and channels, you can learn hard things faster, and produce higher quality output in less time.

In addition, well-documented hAPIs make it easier to integrate new hires or seamlessly hand off responsibilities when someone is sick or away on vacation, enabling a much more flexible deployment of an organization’s attention capital.

And as hinted above, the specificity required to implement hAPIs forces an organization to be transparent about all the ways their attention capital is being tapped, supporting a move toward long term value production and away from short term convenience.

On the other hand, there are many reasons to suspect this human API approach could prove disastrous if embraced.

For one thing, it would be a massive pain to have to reduce the messy ambiguity of the typical knowledge work organization to a set of clearly specified processes and hAPIs.

Even once completed, this approach might not be nearly agile enough to keep up with unexpected needs or demands, creating lots of hard edges at which projects are stalled or opportunities missed.

It’s also possible that my attention capital theory is wrong. The current trend in workflows within the knowledge sector is to prioritize flexible coordination over maximizing cognitive output. Maybe this is actually the best thing to do.

Finally, it’s worth acknowledging the practical difficulty of getting an entire organization to actually buy in to such a radical transformation (for more on this, see Sam Carpenter’s Work the System).

An Ambiguous Conclusion

Something like the human API approach might be the key to evolving the knowledge sector to a new level of effectiveness. Or it’s stupid.

I can’t quite tell.

If you’ve had any experience with this type of approach (for better or for worse) in your own organization, I’d love to hear about it ([email protected]). If the idea sparks a strong reaction in you (for better or for worse), I’d love for you to elaborate in the comments.

30 thoughts on “The Human API Manifesto”

  1. This seems like essentially how a lot of government agencies (specifically thinking like DMV, post office) are run: everyone has specific roles and information flows in rigidly defined channels. This does have the benefits you describe, particularly that people can be swapped in and out of a role very easily. But I wouldn’t hold those institutions up as a paragons of effectiveness…

    This hAPI idea appeals to my engineer side, and I agree that having all communication be essentially a free for all is bad, but it seems challenging to implement something like this without inviting bureaucracy.

    Reply
  2. As a software developer, this idea of human APIs leads my mind to the concept of middleware—software whose only purpose is to translate between two APIs that don’t natively understand each other. Middleware in software is sometimes seen as tedious, but it requires a thorough understanding of both APIs being connected. I wonder how this correlates with human APIs. Do we need greater investments in the people and structures who connect hAPIs? Assistants, messaging tools, bots, or more?

    On a more general note, thank you for sharing your thoughts on this blog. You’ve helped me come to understand the nature of knowledge work better, and I’m trying to improve myself and my team with these concepts. I’m especially glad that I’ve learned to separate deep work from shallow work. I believe in the principle that deep work and constant availability are repulsive concepts (in the magnetic sense).

    Reply
  3. Cal,

    An intriguing thought, particularly if it was paired up with holocracy to provide a consistent way to adapt these processes over time. The biggest differences is that while a computer network is typically set up to only accept conforming signals, people are not easily able to filter out the person next to them.

    Enjoyed the post!

    Reply
  4. Once an organization is created with a well defined vision on what to do for providing value to the world — once you define the game you’re going to play then hAPIs can dramatically increase the efficiency of the system.

    But make sure to allow downtime as well, as you say you cannot do deep work for more than 4 hours per day, people need to be people, else this will be like humans imitating robots.

    I also wonder part of what you say is in the software Capability Maturity Model — https://www.tutorialspoint.com/software_testing_dictionary/capability_maturity_model.htm

    Reply
  5. Love the article, and this is right up my alley! With my last company, we creating frameworks to accomplish something similar and were successful on several fronts (while also failing on others). Since I shut down my business, the project went into hibernation, but I’ve spent the last several years working to move it forward and share. I’ve sent an email with more details and a link.

    Reply
  6. I think people will likely chafe at the rigidity of human interaction protocols and seek to bypass them, especially if they are not efficient. Doesn’t creativity often arise when the mind is at ease?

    Reply
  7. >>> All hAPIs, without exception, must be designed from the ground up to be externalizable. That is to say, the team must plan and design to be able to expose the interface to individuals in the outside world. No exceptions.

    Without the above point, I see the hypothetical organization becoming too internally focused, too idiosyncratic, too alien to be productive in an ecosystem of organizations.

    Regardless of the above point, the idea of hAPIs excites me. What a valuable article!

    Reply
  8. I’m not sure if this is at all similar, but communication with a group of undergrads that I was in charge of overseeing was spiraling out of control between emails, text messages, random office drop-ins, etc. It became hard to manage all of it, so I switched everyone to using Slack as the all-in-one depot for discussing work and projects. All communication had to come to me through that app. In return, I put all work documents, forms, protocols etc. in a folder on the Slack app so that they had everything they needed at their fingertips and didn’t need me to resend anything to them. For the most part it worked, though there was a lot of groaning in the beginning about having to switch from their preferred style (texting) to communicate with me.

    Reply
    • Yes. I saw similar when changing to insisting all learner work was submitted via the electronic portfolio instead of arriving in emails, users spaces with a note, my desk etc.

      It removed the risk of me forgetting work, made marking it in sequence easier, made checking back if it had been done easier – loads of things.

      I think it’s similar to a tech support model “If you want me to fix your computer you submit a ticket with THIS info”, “You do not collar me in the corridor on the way to the loo, add your request to the tail end of an email about something else entirely, shout across the room over coffee etc.”

      No one likes changing to those systems but they’re better overall AND fairer for the end user who doesn’t have to wonder if the simply noisiest or most interupt-y person will get help first.

      Reply
    • I’m trying to solve a very similar problem right now in my residential architecture firm. Clients come at me from 3 or more channels at a time (phone calls, emails, texts, images saved to Pinterest boards, in-person meetings) and we’re losing a lot of efficiency to it.

      I’ve always been wary of project management software because it seemed like I’d just be adding yet another channel to the mix. But I’m actually looking into deploying it now because I can see that as long as I set the expectation at the beginning of a client relationship that we will only respond to questions and comments in the syndicated channel, it could liberate us from the redundant, unstructured communication.

      Reply
  9. I suspect it would drastically affect relationships between coworkers in a negative way. Although I do agree that official requests should be funneled through only one system.

    Reply
  10. In Bezos’ version, the ‘interface’ is super clear and concrete. But, ‘processes’ is vague and not-well-defined. I hope to see an updated version that defines the ‘processes’ in a very concrete way that can improve attention-related issues. In this form, it feels like the result will be a form of bureaucracy.

    Reply
  11. I would worry that this approach sees human interaction as inputs to and outputs from a very mechanistic, deterministic system. That isn’t how value is created from human interaction, in my view: it needs occasions for serendipitous happenings, places where a chance remark can stimulate a new idea, opportunities for someone to argue a point that might change in the course of the arguing, and is based too much on being able to programme interactions in a way that is too machine-like for me.

    Reply
  12. This notion of hAPI is incredibly powerful.

    Imagine eliminating 60-85% of the time spent in one-on-one, info sharing and status reporting meetings as well as 30-70% of the time spent processing email by breaking down information flows in our interaction contexts and devising much more discrete get/give exception messaging via specific slack channel notifications.

    I have begun to help folks do just that.

    Reply
  13. I think there is a tradeoff continuum here. Too many protocols could be stifling. But a good core set of constraints can free cognitive energy and improve output along many lines. Think of how constraining the Limerick form is, but witness the amount of creativity it has unleashed. Rules that constrain the mind from wandering too far give the mind freedom to do more within the remaining space. Human ingenuity is pretty impressive if you study it a while. And when the time is right you can always break the rules.

    There once was a man from Peru,
    Whose limericks stopped at line two.

    And,

    There once was a man from Verdun.

    Reply
  14. To the extent that it would increase the ability to manage focus time, this is a good idea. For management roles that are mostly meetings and interruptions, it might increase the meeting to interruption ratio.
    Perhaps a temporal angle where you could specify not only how but when kinds of communication can happen. Maybe it could be something like, check email and chat 3x/day, make 30 minutes/day (time-windowed) available on your calendar (must book 24 hours in advance), no office phone, personal phone for emergencies only, (other stuff – sys notifications via text or whatever etc).

    Reply
  15. Fascinating post.

    I collaborate with 3 other entrepreneurs in a small training and consulting business. Since using Basecamp and setting up projects and the accompanying tools for each project, our communication is taking place more and more in the right spot. Internal e-mails are almost eliminated, as well as generic chat.

    I could see this working for larger organisations as well, and it will be liberating. Would need to be dictated from the top and everyone should have the freedom NOT to respond to messages arriving through generic e-mail and chat (firing people probably goes too far :)).

    Also, I am “processor” type person so I love the idea. I know I am a minority (most people are visionaries/creatives/operators/doers).

    Reply
  16. The hAPI idea lines up really well with some of the best managerial ideas we know about. Andrew Grove’s “output-oriented approach” turns everything into process. If it worked for Intel, we might want to consider it.
    I think the rigidity of such a system is a balancing act between goals and one’s “mission”. Maintaining a certain amount of rigidity will move you a lot further toward certain goals. Periodically, a company would have to reassess whether or not they should change their processes, but having to adapt them over time is simply a fact of nature.

    Reply
  17. I would love to see a “Case Study” from you on an example of how this would be implemented according to your vision.

    Would this be an example?

    For managing a project, the project manager sets up structured meetings with a reporting cadence that allows the team to do the work and report out a a frequency that allos them to do their deep work yet keep the group informed of progress and issues/risks. The reporting format would be in a standardized format for each meeting to make the meetings effective and efficient.

    Am I wrong in seeing the purpose of the hAPI as eliminating the ad-hoc and moving to more structured interfaces (APIs) to allow for more time for deep work and eliminating distraction?

    Reply
  18. Interesting thoughts! It reminds me of how a support center is run (or at least the one I worked at). Customers can only contact thought an online ticket portal or by calling the support center. Having such a system made it easy to prioritize and distribute the work

    But what about creativity? When you implement a rigid system and eliminate distraction you have the potential limit creativity and serendipity.

    Reply

Leave a Comment