“We like to think we are a technology company, but we started as a service company.”

That’s how Bo Li of ADP, a payroll and HR software provider with more than 740,000 clients, opened her speech at our 2019 API Summit in Austin. It’s said as an offhand remark, but it’s a microcosm for the line that API companies all walk: the balance between doing useful things with technology and properly preparing those useful things for public consumption.

Li is responsible for the ADP Marketplace, which provides APIs that developers can use to integrate with ADP systems. They can then build solutions and sell them on ADP’s platform. The Marketplace is currently home to 300 connected applications with a total of 800 vendors in the process of integrating.

Her perspective is invaluable because, in working with hundreds of API developers, she’s been able to identify a ton of frequent problems they share. Some encounter big hurdles, but, as we’ll see below, there are plenty of smaller, less obvious ones too.

It’s All Technology (And Business)

Building an internal API, or one that’s designed for use by a very small group of people you’re in close contact with is very different to preparing one that’s publicly accessible and regularly used by a large number of people.

In the first case it’s pretty easy for users to email or call the API developer in question, or even swing by their desk on the way back from the coffee machine, to ask how something works. Most APIs quickly outgrow this phase, which is why thorough documentation is so important.

Furthermore, downtime may not be as big of an issue for APIs that are used internally. However, as the appetite for a particular API grows so does the very real risk that downtime and other issues, however minor they may seem, can negatively impact the businesses of that API’s consumers.

In both of these situations, the API is being treated more like a pet project than a legitimate arm of the business. That leads to another significant issue, namely the expectation that would be API consumers care about your product as much as you do. Li explains that API developers often “deploy to a marketplace then, after a few months, say ‘hmm, why is no-one paying attention to my API?’”

This problem is so significant that Li has tried to develop a process for API developers to work through. In addition to asking questions that are useful for ADP – “How do you secure your API? How do you secure your data? How big is your payload size?” – she prompts users to ask the following question: “What problem does your API solve?”

It’s only when API developers think about their product from a business perspective can they start to vocalize why the API is worthy of consumption. Below, are three other ways you can make your API worthy of consumption.

1. Documentation Is King

“When developers think about documentation they think about Swagger, OpenAPI etc., and that’s great. But API specification and product documentation are two very different things,” says Li.

When specification and documentation are treated as if they’re the same thing, the result is a disconnect between what’s promised by specifications and what the API developer actually delivers. To put it another way, “API documentation needs to address it all.”

“Think about the journey of discovering an API, assessing it and then determining if it meets somebody’s needs and really using it. In that journey a lot of different personas are involved,” says Li.

Li provides an example of how a typical API might be assessed for suitability. Rather than a developer, the first point of contact may actually be a non-technical businessperson. They will probably care less about payload and response time than they do the data that it provides.

Those looking at an API from a business perspective will have very different requirements from someone more technologically-minded, or from a developer who’s thinking about trying to work with the API itself. Li suggests that a great developer portal should actually address a wider audience than just developers.

Google’s Apigee portal is a pretty good example of this, as it communicates the value of branded experiences and quantifies how the service increases the adoption of APIs in addition to technical aspects.

2. Creating A Value Proposition

“Not all APIs are the same, and not all are building for the same purpose.”

Sounds straightforward enough but, as Li highlights, API developers don’t always take this into account when thinking about the value of an API. She provides the following example:

“When an API is being used to match a product or service offered by a competitor, putting a dollar figure on the API [i.e. charging for it] may not be the right idea.”

There are three factors to consider when trying to calculate the value proposition of an API:

• Value – Do you deliver that via each transaction? How do you translate it in pricing strategy?
• Cost – Consider both the platform/operational cost and the human cost, e.g. support etc.
• Business Terms – Any usage/call volume limitations or tiered pricing to be considered?

Having talked about the difference between the individuals who may be assessing the suitability of an API Li revisits the idea of disparity, this time focusing on how it relates to those who will be consuming the API.

We know that different consumers have different needs, but it’s important to keep this at the forefront of your mind so you can cater to them as an organization. Li provides examples of those who are building internal vs. external APIs and Clients (developers using APIs to build systems for their own use) vs. vendor consumers (third party companies trying to build a solution to sell to customers).

Depending on the target consumer different situations will require different business terms, policies, documentation etc. That will also, inevitably, have an impact on your pricing structure. It’s why so many products have personal, small business and enterprise tiers.

3. Organizational Buy-In

We’ve already covered the fact that buyers and decision-makers looking at the suitability of an API may not be developers. As Li says, “they may have been told by IT teams to, when they’re validating a solution, ‘make sure they have APIs’.”

She talks about how salespeople must be comfortable talking about APIs, as well as the advantages they offer, and how support teams should be able to “talk about APIs, replicate problems and understand when a problem comes in what data they have to capture to pass that information downstream to a developer.”

For a business creating an API, facilitating organizational buy-in means:

• Capturing information needed for troubleshooting
• Identifying and assigning responsibility for issues
• Logging in all layers and standardizing logging mechanisms, where possible, to give a complete picture
• More detailed information about exception handling, presented in a user-friendly way

“As part of any API rollout program, we need to get [developers], marketing and service people aligned. Otherwise, the whole API economy doesn’t flow.”

She also highlights the ongoing organizational readiness component: “it’s important to get team members ready when you roll out an API for the first time, but it’s also important to get them ready for every step of the life cycle.”

In other words, things like new versions and features should be briefed internally. That’s especially important, Li says, when there are already people using the API; how will we reach these users with news about the API, and who will do it?

Final Thoughts

In her time working with 300 API developers we’re quite sure that, even if she’s too polite to admit it, Bo Li has come across plenty of examples of what not to do when preparing an API for consumption. As a result, she has a ton of insight into best practices and recommendations for developers who are looking to launch an API.

In a nutshell, these boil down to three key points:

• Using an API Specification is not enough when it comes to effective documentation
• Consider what different demographics want to know when they’re researching your API
• Without organizational buy-in, an API is doomed to failure or stagnation

There is, of course, more to creating a successful API than following this advice alone. But, unless you’re taking into account this information as you go along, it’s unlikely you’ll get far enough to find out what any of that is.