This article is the second part in a conversation on APIs. If you haven’t read the first article or are unfamiliar with APIs I suggest starting here: Leveraging those outside your company to innovate

Summary: 

• Don’t look to copy another company’s journey, other successes suffer from survivor bias.
• There are a few clear don’ts with APIs that have been proven time and again to cause failure. These are design don’t not technical don’ts.
• An introduction to my preferred lean design process. APIs follow this same process as any other product does. In short the cycle of steps are Discover, Validation, Mockup, Prototype, Implementation, Evaluation, and repeat. 
• When considering an API consider it as a technical way to change the vertical integration of your business. When creating a product there are always decisions of build vs buy. APIs are the modular building blocks of your business.
• If designed correctly you can recompose APIs as your business changes and facilitate different business models. You can also find your most value add parts of your business to share with partners.

A parable:

Many successes are luck. Viewing only successful products without examining failures doesn’t give us the whole picture. This sort of cognitive bias is called survivor’s bias.

A classic illustration of survivor’s bias comes from World War 2 (WW2). During WW2 the US Air Force was trying to figure out how to increase the survivability of bomber missions. To do this they decided to study where planes got hit on bombing runs. They reviewed all the bombers in the airfields and cataloged the data. 

At first glance you may suggest reinforcing those areas with the most hits would be the best course of action. However Abraham Wald, realized that the planes that returned or survived the fight were fine getting hit in the red areas. The planes that didn’t survive weren’t in the data set, thus Wald concluded that if planes had been struck in the white areas they didn’t survive and those areas needed to be reinforced. 

To mitigate some survivors’ bias, we will first look at the failed set of APIs. The methodology for discovering these outcomes come from personal experience, i.e. personal failure.

Things that don’t work

1. Don’t create APIs hoping to find a user. I was talking to the CTO from an industry leading software company, and asked him if it was possible to create a data strategy led by an API first strategy. He said, “I have seen that tried many times, but I’ve never seen it be successful.” This goes back to the earlier article where creating anything as a business there must be an incentive for a customer to use it. Supply does not generate demand. 
2. Do not create APIs in the jargon/naming/knowledge of your business or underlying systems. This is true of any software but can be especially confusing with APIs. The only interface to an API are words. Consider going into a restaurant where you don’t speak the language or know the cuisine. Frequently they add pictures to simplify the menu. APIs don’t have the benefits of pictures so common non-ambiguous language is important to use.
3. Don’t complicate your API calls. If an API requires dozens of different API calls to accomplish as single task, then not only is this inefficient but it is confusing to the user. This rule is especially important with virtuous or revenue APIs but is a good practice in general. A technical person may complain about “microservices” at this point. It isn’t the granularity that matters it is the usefulness of each grain.
4. Don’t share APIs just because you have some. – As mentioned in my previous article most modern applications, and certainly websites, use APIs. Even if they are good candidates to share, but most likely they are not, they would likely fail don’t do rules #2 & #3. Also you may have systems or SaaS products that provide APIs, directly sharing/exposing those also creates hard dependencies on those vendors locking you in. Make sure to decouple the APIs from the source, a smart developer should be able to easily do this.
5. Don’t copy the APIs from someone else. Just because Domino’s Pizza has an order API, does not mean that Twitter needs to add one. It fits their business model, but says nothing about its universal appeal. After all their success may just be luck. If you really need to functionality from another company it may be best to figure out how to use their existing API.

Product development

In any product development cycle here is my high level process:

When developing any product you consider the supply chain you need to build, burrow, or buy functionality. Usually you’ll consider things like unique value you offer, cost of a component, availability, etc. In software supply chain one of the key parts selections of APIs because they facilitate the interaction of systems, provide data, and functionality to build the end product.

The selection of APIs used is a reflection of your business’ choice (explicit or implicit) on buy vs build. Selecting an existing API or building an API is no different than any other supplier choice. During the discovery process we are trying figure out what the customer will buy and what their experience with our product(s) will be. That user experience is enabled by software through a series of collaborative interactions of APIs. Because of the granularity of these interactions there is far more choice on what APIs to use. This expands the choices of vertical integration of your business software.

Fordlandia 1945 – Ford’s town in Brazil, created to make harvest rubber for tires

To put this in perspective, at one point the Ford motor company bought rubber plantations in Brazil so they could make more tires for their cars. According to Ford’s website, they now have 1400+ suppliers to build a single car. In software the story is similar, some software is built in-house because of the differentiation it provides, Microsoft has over 100,000 developers. However by leveraging Microsoft software, open source software, and APIs, smaller companies don’t necessary need that many in-house developers. For example, Instagram had 13 developers when it was sold to Facebook for over a billion dollars.

Discovery – What to build, buy, or borrow

In the discovery process, we want to describe the customer experience and highlight the key points of customer interaction with the business. This discovery includes human interaction with other humans, human interaction with software, and software interaction. In understanding that process we can understanding what part of your business we turn into software and of that software what do you to build, buy, or borrow.

During discovery you may be tempted to make the APIs about the interaction in the process because that is what they facilitate. However for reusable APIs you want to pick the nouns not the verbs out of these interactions. This allows the interactions with a noun to be varied and business models to be varied as well.

If you have ever seen magnetic words on a refrigerator that you can shuffle the words around to make new sentences, then that is the idea here.

For this exercise we will pretend to be a small restaurant owner, and you create several types of meals for your customers to eat. Your business is doing well and it is time to upgrade your point of sale system from pen and paper. As you observe and describe a customer’s experience you can highlight the nouns as opportunities that you need your software to do and thus what APIs you need.

1. A customer comes to our restaurant and seats themselves.
2. A waiter goes over and takes an and sends it to the kitchen.
3. The kitchen looks at incoming s, then makes the corresponding
4. When all the in an is ready, then kitchen places the  in the pickup window. 
5. The waiter checks ‘s and hands the customer their .
6. Once the customer is done eating the waiter puts down a check requesting

By pulling out some of the nouns to be APIs let’s look at the types of restaurants our new point of sale system can support:

This gives us the flexibility to change our business overtime. But there are a few nouns that were missed in this evaluation and you may want to consider. 

Customer – Customer wasn’t captured which means we can’t track our customers. This may be fine but it also may be a mistake, how can you send out targeted ads?

Employee – Who is taking the order? Does it matter? Who has the best upsell on the food with the best margins?

Discovery is an iterative process. But spending time in conversation with post-its (my preferred form of user experience mapping) minimizes the waste of writing and updating software.

At this point we may want to start validating what makes our business unique and what problems we are trying to solve. For this example we will assume we have the right problem, a lack of a point of sale system. Here are some questions we should find answers to:

• Is there a point of sale system that does everything you want?
• What software capabilities do you need to inventory ?
• is something we have no interesting in building or buying because Venmo and Paypal offer that for a small usage fee. But does plug-in seamlessly with whatever point of sale software we build or buy?
• Lots of times our customers come in and say they are feeling sad and we provide an order that will make them happy or they say they are feeling anxious and we make food that will help them be calm. It is one of the reasons we have lines outside our door? It is unclear if normal off the shelf APIs will be able to handle what is actually our competitive advantage.
• At the moment seems like a buy may be a build and is burrow/buy.

Mock-up : With OAS

Once you have the use case(s) you want to solve, then it is important to validate any assumptions made during the discovery process. One of which is that you need to build an API and you need to buy a API. One of the most important forms of validation is usability testing. If people can’t use your product then there is no value to be gained. Unfortunately people are bad at telling you what they want to use but great at telling you when something is wrong. Mockups are a cheap way to accomplish this. A mockup can be as simple as a drawing of what you think the final product might look like. Ideally there are several options of what the final product would look like to triangulate on the best combination of ideas.

One of the nice things about the ubiquity of APIs is there are lots of software mockup tools to use. Remember the user of a APIs is a software developer, so these tools are designed for them. The goal here is to de-risk any things that would make an API unusable, i.e. jargon, system information, interdependency, etc. Since the developer is doing the validating they need to be part of the discovery process so they know what they are checking for in the mock-ups.

One of the best ways to mock up APIS is by creating an Open API Specification (OAS) document. This document can be used for the mockup, prototype, final implementation, and later sharing an API. It creates consistency through the life cycle API product development process. It will change and evolve along throughout the process capturing and sharing the consistent understanding of what the API should be.

Here is an example of an OAS from Revel, a point of sale software company. Unsurprisingly they have an Order API. You can see they have an tool to share the OAS with their potential/current developers. 

You’ll note there is a big “Try it!” button in the bottom right corner. This allows a developer to try the API before they buy it. It also provides various implementation examples in popular development languages. They are definitely catering to their user, the software developer. Let’s assume after using the Mockup your development team verifies you do need to build , nothing like this exists in the market today. But they could use Revel API.

Prototype – Wizard of Oz 

Pay no attention to the man behind the curtain

No this isn’t an image from an investor meeting. This is from the famed movie “Wizard of Oz”. One prototyping method is called “Wizard of Oz” Prototyping because the interface looks like it is all powerful (see picture above) but the actual implementation is someone running around manually flicking switches making it look good (see picture below)

 Zappos, the online shoe company, famously used this method when they started their website. In 1998 

He reserved the domain name Shoesite⁴ and without building out any sort of inventory system, he literally walked down the street to the local shoe store, took photographs of their shoes, and posted them on the website. Several months into the project, Nick was getting $2,000 worth of orders per week. They weren’t making any money, because after an order was placed, “Nick would run to the local shoe store, buy the item, and then ship …

– The Lean Entrepreneur by Cooper & Vlaskovits  

This can be used with APIs as well. Sometimes APIs could skip this step as the implementation of simple APIs can be as fast as creating a prototype. Prototyping can be useful when the API would be very expensive to build, like adding a machine to a factory. Before you buy those machines it is helpful to see how often the API is called. It could be that manual labor is far more cost effective than automation.

I have used this type of API prototyping before when building automation for enterprise software. Initially it wasn’t clear what our customers would change most frequently. By creating an API that plugged not into automation and cloud systems, never free, we had it create tasks on our work management tool (aka Jira/Rally/ToDo lists). By implementing this way we discovered what had the highest change rate in our system and automated that first. Those things with little or no change we automated last. Some steps we keep manual, like validating funding, but from a system automation standpoint the customer had no idea there was a team behind the curtain. 

In our example, at this point the restaurant’s developer creates an ordering app for the waitstaff. It combines a PayPal with a Wizard of Oz and your trial edition of from the Revel. After taking the , the waiter hits a submit button. This submission sends an email to the owner. He reads the email and translates in his head the customer’s need to feel cozy and mentality translates it, ex. mulligatawny soup. He writes an order down for that and hands it to the kitchen staff. This is likely only a few lines of code and his held together with human glue and the owner being the man behind the curtain.

Evaluate: Analytics without Assumptions 

Once you have a website/application/API it is time to find out how it is being used. The earlier you can find this out the better. Find out which APIs are called most frequently in your app, there are lots of tools available to help you with this from web page analytics or API tracking/management software. Using these tools you can categorize usage in various ways. In our pretend example let’s assume there are 3 clear winners for the most used APIs:

The real question here is why? We have come back full circle to the discovery process. This process will look different than before because we have some data and a new environment in which we have a point of sale app. The data is the start of the story not the end of it.

 It could be that the API with the custom FeelBetter-Food-Selection AI backend maybe an opportunity for a virtuous API.

Usage:  

• Map out your user’s experience, this is the lowest cost way to validate you are building or buying the right product. When evaluating a software product ask: Does it match our customer’s experience? Does it enable our current business model, and does it have the flexibility to grow with our business?
• Mockups and Prototypes are a cheap way to validate usability assumptions before going to the expense of building a full product. This works for product development as well as product selection.
• Use analytics to see which APIs in your applications are being called the most. See if those are candidates for a different market, either reuse, revenue generating, or virtuous.