#product #apis - 7 mins read

Your API is a product

There’s a good chance your company either consumes or provides an API. Perhaps both. On all of the products I’ve worked with over the last five to ten years, it’s been rare for a quarter to go by without my team turning its attention to one API or another.

And they’re big business.

API product revenue contribution

More and more companies are beginning to realise that APIs are products in their own right, and should be treated as such. In many ways, they’re much simpler to build, easier to manage, more scalable, and, ultimately, they can be significant revenue and growth generators.

“Salesforce.com generates 50% of its revenue through APIs, Expedia.com generates 90%, and eBay, 60%.” Harvard Business Review, 2015

What is an API?

At its core, an API (or application programming interface) is a mechanism provided by one system to another to enable the two systems to interact - where one effectively sends messages to the other.

I equate them to a paper form that you fill out when you sign up for, say, a new dentist. The form is the dentist’s API - the mechanism that they provide for you to use an element of their service.

These messages will need to be of a certain shape and size - both in terms of the overall format of the message (e.g. JSON, XML), and the intricacies of each individual data item (e.g. mandatory vs optional, data type, character limits). The consumer may need to adhere to certain protocols, such as authentication, and may have to agree to other conditions of usage.

The rise of the “technical” product manager

During my two decades in tech, I’ve observed the continued shift towards cross-functional teams who own a whole, or part of a product, and an increase of dedicated product managers within these teams. In the early days, the vast majority of teams - and particularly teams that had PMs - were for customer facing products that had graphical user interfaces; think websites and web apps. APIs were few and far between - often a poor relation, or something considered “techie” and not a product concern. Perhaps even viewed as more of a cost-centre. An overhead. A necessary inconvenience.

Over time, as the momentum continued, more PM-led, cross-functional teams sprang up to look after more nuanced “products”, be that internal systems, abstracted platforms, or indeed APIs. Not only has this seen a rise in the number of roles titled “technical product manager” over the last decade or so - a role that usually covers the typical responsibilities of a PM but acknowledges that they’ll be operating in a more technical, less traditional and accessible domain - but has also meant that product managers across the board have been expected to have exposure to and at least a base level understanding of APIs.

Getting to know APIs

If you don’t yet work on an API as such, a good way to learn is to lean into the appraisal of a third-party API, should the opportunity arise in your team or wider organisation. Sometimes this is the responsibility of a tech lead, or perhaps a business analyst, but it can be a good exercise to help you develop an appreciation of what APIs are and how they work.

I wrote “Third party integrations and the importance of tech discovery” last year about this very subject and would suggest you start there. Or if you’re feeling brave, you could dive straight in at the deep-end and have a go right now at appraising which API provider is the right post code look-up for your fictional ecommerce website based on their API docs - getAddress() for example.

API documentation

Learning the basics of API documentation is more than half of the battle - doing so will enable you to quickly absorb the capabilities an API provides, and visualise how it may complement your existing product suite.

There is a lot more to API docs than this, but the two most useful concepts for me are:

1. An overview of the API that lists out its endpoints by name, ideally with a few sentences of description

Think of each endpoint, sometimes referred to as operations or services, as a user story - it’s performing an action on an object e.g. view a list of orders, view order details, update customer details - that sort of thing. Understanding the basics of HTTP methods can help here, and is easily enough translated into CRUD actions which anyone who has worked in software development for even a short time will likely have grasped.

If an API is documented in a tool such as Swagger, then you can normally see this on first landing on their documentation hub, such as in this Petstore example. Hopefully the endpoints have been sensibly named and you can immediately see the things that a user of the API can do.

Sometimes APIs are documented in a more bespoke fashion, but the best ones all lead with an overall view. At time of writing, Dropbox has them all down the right hand side of the page, GitHub down the left.

This is always the place to start when trying to get a grounding on the high-level capapbilities of an API, and what it can and can't enable you to do.

2. An example request and response

If I keep going with the Petstore example, as you drill down into each endpoint, it gets into the nuts and bolts of what gets passed one way and then the other. If you think of the end point as correspondence, or simply a conversation, I find it quickly becomes much more relatable. So this endpoint that “gets user by user name”:

Get User by Name

The caller asks for the details of a user, providing the username. The responder uses the username to look up some details, and returns the standard stuff that you’d expect - name, email, password, status etc.

If you’ve locked in a capability that you want to build using an API, this is where you come to work through the lower-level detail. Could I use this endpoint to show the user’s profile image in my SaaS portal? No I couldn’t, as it doesn’t return anything image-related.

Story mapping an API

Being the story map nut that I am, I like to go one further than classical API docs. The very operational naming convention of API endpoints lends itself perfectly to the verb/noun approach of story mapping.

I find a story map is much more accessible. As much as I like getting stuck into a suite of API docs, time and again I find the story map is always the artefact I go back to when grounding a conversation, talking about priorities, or introducing newbies to an API.

Here's a crude one I've knocked up in a few minutes for the Swagger Petstore example:

Petstore Story Map

Hopefully it shows how you can make something a little warmer and easier to absorb than the landing page of API documentation - particularly for a less technical audience.

API metrics

Most PMs have a good handle on indicators of health of a more traditional product - the usual suspects, such as pirate metrics - but what about if your product is an API? In my experience, there’s no reason why you can’t treat these exactly the same. In many ways, user behaviour is much more fixed and therefore easier to measure.

And the user and buyer experience is just as important, and can be measured in much the same way as any other product - CSAT scores for example.

User experience and research

Often overlooked for API products, but the best orgs out there will treat APIs no differently from customer-facing web or mobile apps. They’ll have very clear user and buyer personas. They’ll have regular touch points with real customers. Beta communities. GOV.UK provides some great advice for building APIs with user needs at their core.

In summary

Yes, your API is a product. So why not treat it like one? Be clear on its value proposition. Define your aims and how you plan to get there like you would a more traditional product - a decision stack is a good place to start. Consider monetisation. APIs are often perfect candidates for product-led growth, given the standardisation of onboarding, documentation, and utilisation.