Winning with APIs

If you just focus on the smallest details, you never get the big picture right.  – Leroy Hood


I used “What Makes a Great API?” as the working title for this penultimate post when I began this series. However, that does not get to the heart of what I was really after.  I want to formulate an understanding of how to achieve our goals with APIs – I don’t want the mere existence of APIs to be the only outcome.  I want to distill those key characteristics of APIs that beget success so I can focus on the right things at the right time.  I want to avoid a narrow view of how to design an API based the latest dogma spouted into the mist of the software Cambrian explosion.   I want to win with APIs – and I want to do it as efficiently and economically as possible.

What does winning mean for you?  Do you know your destination?  You could design the most compliant and beautifully RESTful API in existence, but if you miss that specific functional need or the core API characteristics that will get you to your destination, you have achieved nothing.  This obviously means you must know your destination – or at least an approximation of a destination – to guide your journey.  So, this is where we will start.

Why APIs?

An understanding of your business model, objectives, problems and opportunities will provide the purpose and constraints to identify candidates for APIs as well as inform decisions as you implement them.  APIs are not just a technical pursuit and must align to business concepts.  This is really no different than any other software design.

Consider these example opportunities that an API solution can address:

  • Ecosystem – To provide access for your partners and clients while supporting the growth of your platform via a rich interaction with contributing partners who add to and enable unimagined use of your platform; examples include:, Twitter, eBay and
  • Flexible Processes and Clients – To support evolving business opportunities, new distribution channels and new technical channels such as a mobile, wearable devices, wellness devices or other unknown future opportunities in the Internet of Things.
  • API as a Product – To support a business service model with the API being the face of the business as the primary interface for clients and partners; examples include:
    • Direct revenue from data or transaction services via API such as PayPal, Stripe, Melissa Data and MailChimp
    • Indirect revenue from services such as (Affiliate Program), Flickr, and travel sites like
  • Architecture and Asset Management – To support flexible, effective and efficient platform development, evolution and management with a componentized architecture.

Your business and management objectives determine the structure of your API as well as the emphasis you apply to certain characteristics during design, creation and management of your API.  That emphasis will naturally rely on application of some constraints, so it is important you are making fully informed decisions.  For instance, designing only for “data exchange” will drive emphasis on exposing your value through coarse gained interactions and less emphasis on componentization since facades serve the need just fine.  However, it is likely you will not be able to achieve expected value for “Flexible Processes and Clients” or “Architecture and Asset Management” with the same design due to lack of focus on assembly and componentization.  That is OK – as long as long as those things are not important for you to win, you are aware of those constraints and keep your eye on your specific objectives.


Why Great APIs?

Having good APIs can help you address the immediate delivery of your capability, but to win with APIs, you must have “Great APIs”.

  • APIs will live forever once you release them into the wild – by their nature, APIs are directly embedded in consumer (clients or partners, internal or external) systems which increases sensitivity to changes you make. Poor APIs will burden you forever with high maintenance effort, limited agility or even suboptimal delivery of your capability.  In short, you will never really deliver what the consumers need to grow (ultimately retain them and extend their business) and you will spend all your effort surviving what is there instead of thriving with your platform.
  • APIs will drive access to your business – APIs are the face and entrance into your business. Poor APIs will limit the use of your capabilities by your consumers (clients or partners, internal or external).  If it is too much trouble, they will give up and go elsewhere.
  • APIs will drive how you grow your business – APIs are the entrance to your business and an opportunity to define and manage your assets. Poor APIs and lack of componentization will limit your ability to rapidly extent, evolve, manage and efficiently organize for your platform; you may be trapped forever in a design modeled 15 year-old market need instead of the business model you need tomorrow
  • APIs will drive your productivity and agility for responsive growth – APIs are an opportunity to define and isolate your assets. Poor APIs and architecture will limit your ability to pivot and organize your teams to address new opportunities and the inevitable shifting market priorities.


Characteristics of a Great API

Any time I have asked developers to describe characteristics of APIs they have “enjoyed” using, the reply is invariably an API that can be easily understood with minimal, but good documentation and solid examples.  Beyond that, they want APIs that are easy to find and make it easy to find what they need to get started.  After all, they are looking for help to solve some greater problem, not the additional problem of how to use an API.

The greatest irony is that developers love to hate many of the APIs out there.  Developers build APIs for developers, so how can this be?  Sometimes haters gonna hate – our software industry is full of finicky and egotistical characters.  However most people I have worked with want to do the right thing and the problem more commonly lies in the fact that developers lose empathy for the intended audience in the rush to get their interpretation of business value exposed.  Even worse, many product leaders think APIs are a purely technical pursuit and fail to define the core business purpose of the API, so that interpretation is misinformed.

We can address these problems by taking a page from our companion discipline that must also consider our fellow humans – User Experience (UX) Design.  We too can leverage User Centered Design to define purpose, and then focus our lens on the “Developer Experience” (DX) to invoke empathy for our friends that will be using the API.

John Musser of API Science and addressed these points and more in his presentation on “What Makes a Great API” which includes “5 Keys to a Great API” (valuable, planned, simple/flexible, managed/measured and supported) coupled with his “Top 10 List of Worst Practices”.  This is one of the most comprehensive views I have seen on what makes a “Great API” and is based on over 10 years of analysis of the open APIs cataloged on  While his focus was on open APIs, the lessons can be extended to any use.

We must remember that an API is great if it can be composed into something more useful.  To be composed, we need APIs that are useful, usable, and used.  APIs that are Used is our ultimate objective – we do not get any value until an API is used and we are able to retain and then extend that use.  That will not happen if the API is not usable.   Obviously, no one will even try to use the API if it is not useful.

That helps us round out our framework for the “Characteristics of a Great API”:

  • Useful API is Planned
    • Outcomes – Well-defined mission, goals and purpose of the API
    • Business Model – How you make money with the API so you can design to the model (API for the model, not API is the model)
    • Business Use – What context the APIs will be used and significant use cases
    • Audience – Well-defined stakeholders, including business and technical perspectives
  • Usable API has Empathy for our Friends
    • Purpose – Useful, valuable, appropriate to the audience, has a purpose and fulfills the purpose
    • Usable – Simple/understood, consistent, composable, hard to misuse and easy to learn, use, extend, scale, maintain, upgrade and operate the API
    • Testable – Quality offering (does what it is meant to, well), easy to verify and minimal complication.
    • Cared – DX support, communication and communities
    • Fit-for-purpose – Pragmatically designed to balance its purpose, the profile of the target audience and usability to ensure value is actually extracted from the API
    • Discoverable – The right capability is easy to find within the API and it is easy to find what is needed to use the API
  • Used API must be Managed so it remains Useful
    • Secure– to address the information risk at hand, protect the user and balanced fit that risk while also being usable
    • Adoptable, Adaptable and Durable – to drive initial adoption, but also retention and growth for consumers and your business model through extendable/evolvable design – self-protecting against untrustworthy consumers, but balanced with some forgiveness/adaptability since all consumers may not be Tolerant Readers
    • Managed – to ensure uniformity and continuity across the API domain (noticeably planned), minimizing surprises, intuitive evolution and responsive to trending changes
    • Supported – DX care, operations care, communication, communities and tooling to support all lifecycles
    • Measured and Visible – to ensure you know your API is working and working well
Useful, Usable and Used

As you embark on your own API program, it is import to remember that it is not just a technical endeavor, even if you would intend it only for an internal audience.  Your goal is to ensure it is used, which means you must start by understanding what is useful and manage it to ensure it remains useful.  You must maintain an empathetic eye during design and provide developer support to ensure it is usable.  Spiced with the right amount of pragmatism, this will set you on your way to not just creating an good API, but a great API you can win with.