APIs Explained for Product Managers

The ‘techie one’.

As product people, we’re often referred to as the ‘techie ones’ by business, sales and marketing stakeholders. We get invited along to external meetings to go through the details of how an API integration might work, we attempt to explain (with great patience and a smile on our faces) the technical restraints to our business colleagues of a particular feature and we evangelise the impact new technologies can have on our products and our business.

Yet our engineers still sneer if we attempt to be remotely technical when tackling problems. We’re managers, not engineers, in their eyes. And rightly so; we’re not engineers and we shouldn’t try to be. Product Managers have a penchant for fancy notepads, colorful socks and user metrics. Engineers love ruby on rails, funky javascript frameworks and nutella sandwiches at 10am on a Monday morning. We’re different.

That leaves us in a tricky position where the business sees us as the techie people and our engineering teams think we’re ‘managers’ with no real competent skills in software development.

So what happens when you’re working on a product that is more technical than you might perhaps be comfortable with? What happens if you’re dropped into the deep end and you’re drowning in technical documentation and have no idea what any of it means?

Well, in true product management style, you’re expected to soak it up, learn on the job and get on with it.

Technology skills are part of the holy trinity of PM skills: business, technology, design and there is a strong case both for and against product managers having technical skills. My own personal view is that technical skills are an asset to product managers on the condition that the product manager’s focus remains on delivering the ‘what’ i.e. the value to the customer / business and that the ‘how’ (the technology) is viewed as the mechanism of delivering that value to the customer.

If a product manager had to survive with only 1 skillset, it would not be technical skills. I’d argue that customer empathy, strategy, business, communication and design are more important as core skills, but that technology skills can strengthen decision making, help to understand trade offs and clarify potential business opportunities when used appropriately. Getting involved too deeply into the technology results in an unhealthy focus on the ‘how’ which misses the point of product management entirely.

Introducing APIs

Of all the web technologies, APIs are seemingly more and more important to product managers as more and more products offer APIs which do cool things and open up new opportunities for customer growth and revenue.

In my experience, APIs are one of the most frequent technical concepts referenced by non-product/engineering stakeholders because of the business opportunities they present. An understanding of the fundamentals of APIs is therefore a very useful thing to have.

In this post, we’ll examine what APIs are and what the most important things to learn about APIs are as a product manager so that you can apply some of this knowledge in your daily role as a product person both in your conversations with stakeholders and your engineering team.

Why are APIs important for product managers?

The business case for APIs

APIs open up a whole world of new product and business opportunities. To get the full benefits of these opportunities businesses typically utilise APIs in 3 different ways:

1. Integrating with third party APIs
2. Building your own APIs for internal use
3. Building and exposing your own APIs to your customers

As product people, I’d argue that we’re more concerned with 1 and 3 since these are where the opportunities for adding value lie. Building APIs for internal use isn’t something I’ve been heavily involved with and is something I’d normally leave to the engineering / architectural teams to decide.

1. Integrating with third party APIs

Connecting with other companies’ APIs allows you and your product to fast track adding features, functionality and tools that would otherwise take you and your team years to build. Chances are that you / your team have worked on integrating with an API at some point. Typically you’ll talk through a feature set and your engineering team will know of an API that will handle the task you need to do via a third party.

Most products today utilise integrations with APIs in one way or another. Here’s a few examples of open APIs that are widely used by millions of websites around the world today:

These are all examples of how you can utilise integrations with third party APIs to offer new features and functionality in your products.

To dig a little deeper, let’s use Uber as an example of how multiple sets of APIs can be used in combination to create value propositions for its customers.

Uber uses several APIs to deliver its value, including some of the obvious ones which I’ve highlighted here:

1. The Google Maps API to display the customer journey information and set your pickup location. The Google logo is visible on the map.
2. The Braintree API to process customer payments.
3. The Twiliio API to send comms to customers about their journey e.g. ‘your driver is on its way.’

Typically, products will include a mixture of internally used APIs for internal services, APIs which are exposed externally and integrations with third party APIs to offer new value to customers.

To summarise, some of the main benefits for connecting with third party APIs are:

However, before you get carried away, it’s not all a bed of roses. There are some downsides to using third party APIs for the core of your product which need to be considered:

2. Exposing your own APIs

Should you expose your own APIs? Well, it depends entirely on what your product is / does and what your business goals are. If creating your own APIs means you’re going to get X number of new clients which means you’ll achieve your quarterly growth targets then it’s worth considering. If it’s a colleague’s pet project that demonstrates no clear business value then don’t.

For some businesses, APIs are the business; the value the company offers to customers could not exist without APIs since the value is delivered through APIs. Some examples of this include Twilio which allows companies to send text messages to customers based on user actions. Shutl is another; it leverages integrations with local couriers and local retailers to create an entirely new value proposition – same day delivery. Without the ability for merchants to connect directly into its APIs, Shutl wouldn’t have integrated clients and as such would not exist as a business.

So for some businesses, it’s a no brainer; it’s a fundamental part of your product which underpins your value proposition and you therefore need your own external APIs in order to provide the value your business exists to provide.

However, you may be in a position where you’re considering exposing your own APIs, but they are not necessarily a fundamental part of your business and are more of a tangential opportunity which may or may not work out. Your stakeholders might argue that your clients really want an API that does X,Y and Z but you’re not convinced of the opportunity.

So what do you do?

Before you decide to build expose your own APIs, ask yourself some of these questions:

1. What is the business impact if we do create our own APIs? How much additional revenue or how many more customers are we going to get? Does having an external API get us closer to our goals? Be as specific as possible in your projections and get some data to back this up.
2. Is your company ready for additional costs and overheads in managing the potential infrastructural complexities of an external API? Clients will need hand holding and managing and APIs that are widely used by clients will drive up your infrastructure costs.
3. If you do build one, how will you demonstrate the impact it’s having on the business? Many execs don’t tend to understand the intricacies of APIs and you need to ensure you’re in a position to manage the exec team so that they understand what impact an externally facing API has had to your business. If it’s not likely that you’ll be able to demonstrate its value, seriously consider whether it’s worth it.

Why not run an API appetite experiment?

In true lean product fashion, one way to quickly assess the potential impact of an external API is to write up some docs / landing pages for an API before you commit to building one and drive some traffic to monitor how many potential customers sign up beforehand. You could also ask your sales team to mention the possibility of an API to enterprise clients and keep a record of the appetite to see if there’s a genuine business appetite or not.

If you do make the decision to create external APIs, get yourself a highly skilled architect and if you’re not too technical yourself consider hiring a technical product manager who specialises in API design. The technical PM won’t write code but they will have a fundamental understanding of good API design. This, coupled with an understanding of what the market wants can shape the design of your API.

If done effectively, creating external APIs can open up a world of opportunity and generate significant additional revenues. Spotify, Facebook, Google and Braintree are just some examples of companies who have benefitted tremendously from them. But it’s not just the large corporates; nifty startups in particular can see their growth trajectory explode due to opening up their APIs and evangelising them in the developer community.

One thing that puts off some product managers is that they don’t fully understand how APIs work. You may be in a position where you’re prioritizing features that you know there is an appetite for and you fully understand against a suggestion from your engineering team to develop an API which you don’t fully understand and therefore decide not to prioritise.

That’s dangerous prioritisation rationale since you’re allowing your own technical ignorance to impact potentially business critical product decisions. I mean ignorance in the nicest way possible btw; we’re all ignorant of 99% of the world’s information. 🙂

OK, now onto some of the more technical bits.

What does API mean?

API stands for Application Programming Interface. You might know that already, but does that help to describe what they do? Not really.

APIs allow two systems to communicate with each other. The best description I’ve heard is that an API is essentially a form of contract between the two systems and the API documentation determines the terms of that contract. An API is designed to a specification and in order for information to be transferred the rules of the specification must be adhered to.

To understand APIs we need a basic understanding of clients, servers and HTTP.

The client (your web browser), speaks to the server and says ‘hey, show me that picture of a dog you have’.

The server (where the files or resources are stored) says ‘sure, here it is’.

This process works is using HTTP. HTTP stands for hypertext transfer protocol and describes the transfer of information over the web.

HTTP requests are the foundation of the web. Take a look at your browser to prove it. HTTPS is a more secure version of HTTP where information is encrypted.

Your browser makes HTTP requests to a website’s server every time a new page is loaded and it is something called HTTP methods which are used to tell the server what to do. These methods are also used by APIs. More on these later.

Once you have an understanding of HTTP and the transfer of information between a client (your browser in this case) and the server (the server which is ‘serving you the content), you have an understanding of the foundational elements of APIs.

Let’s dig a bit deeper into the specifics.

The 10 most important terms you need to know about APIs

Here’s what I believe are the most important things you need to know about APIs as a product manager. This is based on my own humble experience and not much else. Learn these concepts and you’ve got a solid foundation to speak about APIs with confidence to stakeholders and your team.

There’s quite a lot to digest here and it looks a little overwhelming. So let’s take a deep breath and tackle 1 piece at a time.

1. Requests and responses

At a very basic level APIs work using ‘requests’ and ‘responses’. This video explains things v. clearly.

I request something in a specific format as outlined in the API documentation and the API responds with something in return.

For example, using the Spotify API I can request a list of songs from an album.

In order to do that, the following needs to take place:

1. I send a request to the Spotify API
2. As part of my request I tell Spotify which album I want to retrieve a list of songs for using an ID e.g. Spice, by the Spice Girls (a classic) has a unique ID
3. Spotify responds with a list of songs from the Spice album in a language called ‘JSON’

The API documentation will specify what the request should be and what you can expect in the response.

2. REST

REST is what you do at home with a glass of wine after a sprint planning session went badly and your engineering team want you killed before the next sprint starts.

Crude jokes aside, you’ve no doubt heard the term REST or RESTful used in several blogs and by your engineering team but you may not have any idea what it means. There are plenty of people who could spend the next 6 months talking about REST but let’s keep it as simple as possible and learn the basics.

REST stands for representational state transfer and whilst that sounds ridiculously scary it is used to describe a set of architectural principles and characteristics outlined in a document in the early 2000s by a guy called Roy Fielding. The document lays out a series of principles which should be followed in order to create a RESTful API. Thanks Roy.

Think of REST as a set of members club rules. The owner of the club is saying, ‘hey guys, look, if you want to be part of this REST club, you’re going to have to follow a certain set of rules.’ Kinda like a religion, but less scary and more rational.

What are the characteristics of a RESTful API?

We don’t need to delve too much into these (especially since they’re a little dull) but this video goes into more depth for each of these explanations of a RESTful service if you’re interested in finding out more.

So in summary, REST is a set of principles which need to be followed in order to classify your API as a RESTful API. This uniformity makes it easier for developers to work with multiple different APIs. You don’t need to learn API specific methods; you can use REST principles for all REST APIs. Unless you’re an API product manager, that’s all you need to know. And perhaps the most important takeaway is that REST APIs all use the same HTTP Methods:

• POST
• GET
• PUT
• PATCH
• DELETE

What on earth do they mean? Glad you asked.

3. HTTP Methods

When working with APIs, something called HTTP methods are used to request information. The methods are the ways you do things with APIs. Think about how you would interact with your pet as a weird, but potentially helpful analogy. You would say ‘FETCH’ if you wanted your dog to get you something, ‘SIT’ if you wanted your dog to sit and ‘PAW’ if you wanted your dog to raise its paw. The way we work with HTTP methods is similar in that they describe various ways in which you can get things done.

The most commonly used HTTP methods are: POST, GET, PUT, PATCH, DELETE.

If resources are nouns i.e. ‘things’, each of these methods is a verb which does something. HTTP methods can create, read, update and delete information (CRUD is used as an acronym).

The most commonly used methods in my experience as a product person are POST and GET, which allows you to create or read and retrieve information. GET is straightforward and is considered the safest of all the methods since it doesn’t update any information.

Here’s a summary of the most common HTTP methods:

4. Endpoints

An endpoint is a place.

It’s a connection point which accepts requests to access resources on an API. An endpoint needs to be ‘exposed’ so that it can be called. Think of it as a door which can be opened or a socket in which you can plug yourself into and get what you want.

In this API endpoint reference from the Spotify API, you can see a table which contains:

• The HTTP method e.g. GET (which is used for reading and retrieving information)
• The endpoint e.g. /v1/albums/{id}
• The usage – what the endpoint is used for e.g. in this case it’s used to get an album’s tracks
• Returns – what is returned in the response from the API

If we look back at our Spotify example, we’ve now added further information including endpoints. Let’s understand how the endpoint is used…

5. API Documentation

As product managers our primary concern is not with the design of APIs as such, unless you’re a technical product manager who specialises in APIs. We are mostly concerned with the functionality and business value an API can offer to our customers and the functionality of an API is typically outlined in its documentation.

For some product managers, your first foray into APIs comes when your team mentions an API and asks you to get the documentation from a third party. On first glance if you’ve not worked with APIs before documentation can be a little overwhelming as none of it makes much sense.

If you’re not familiar with API documentation, check out some examples here:

Spotify Documentation

Twilio Documentation

The primary purpose of documentation is to lay down the rules of the ‘contract’ and to help your engineering team understand what functionality is available by using different API calls.

In the documentation you’ll notice a familiar set of terms, which are commonly used across all APIs. That’s one of the benefits of using the REST principles; REST APIs make use of common methods which makes it easier to integrate into multiple APIs.

API documentation will typically include many of the following:

• Authentication instructions – how you connect with the API
• API endpoints – what endpoints are available
• Resources – what resources are available for you to access. For example in the Spotify API, they allow to you access Playlists, Albums, Artists, Songs
• Request format – how an HTTP request to the API should be formatted
• Response format – how an HTTP response is formatted when you receive the response
• Response codes – what response codes are included in the response (we’ll talk about these later).

6. API calls

We refer to the requests to APIs as API calls. Not telephone calls but exchanges of information.

API calls involve hitting an endpoint with the expectation that the API will respond with the information you need.

In the Spotify example, you call the albums endpoint with a specific album ID and Spotify responds with information about that album.

7. Payloads

You’ll sometimes hear engineers refer to the ‘payload’. This is a fancy way of talking about the response from an API.

It refers specifically to the meaningful information in a given set of data. Not everything in an APIs response is something we care about, so the term payload is used to distinguish between the stuff we’re interested in and the stuff we’re not.

E.g. ‘If you check the payload from the Spotify API you can see the length of the track is 3 minutes’

8. Response codes

Every time you get a response from an API, it comes with its own response code, which is simply a number with a meaning attached to it.

There are plenty of others so this list is by no means exhaustive but it’s enough to give you a foundational knowledge of the most frequent so that when people talk about ‘a 500’ you’ll know it’s a problem with the server.

9. Headers

When you send a request to an API, your request will include something called headers. The response from an API will also contain headers.

Headers are additional useful bits of information which are sent and received along with your HTTP methods. Some headers are mandatory and some are very rarely used.

Some of the most common headers are:

• Authorisation – the authorization / authentication credentials such as username and password
• Content-type – this determines how the information is presented back to you and what content is used. JSON is the language typically used by APIs.
• Date – represents the time and date of a request or a response.

This is an example of some headers that are sent with an API request on the Spotify API.

10. Authentication

In order to interact with an API and in order to establish your connection with the API, you need to tell the API that you’re not just some random idiot and that you’re a genuine, bona fide user who has the necessary privileges to access the API. In order to do this, you need to access APIs using an authentication token.

In the same way as you would authenticate yourself when logging into your email or Facebook account using a username and password, you need to do something similar for accessing APIs.

If you have an external facing API which needs to be accessed by clients, they will typically be issued with a security token and credentials which they will need to use to access your API.

There’s a subtle, but important distinction between authentication and authorisation.

• Authentication – proves who you are
• Authorisation – defines the what you are permitted, or authorised to do

Authentication usually includes:

1. Username
2. Password
3. Access token

If you have a product with an external API, your third parties will be given a username, password and access token to access your API. Often, a token can be provided in the sandbox environment to allow their developers to play with.

OAuth

OAuth is an authorisation framework that can also be used to authenticate and authorise users. Using OAuth involves a separate authentication server which authenticates the user and then passes them back to the resource API.

Bringing it all together

So that’s enough theory, the best way to learn these things is to play with them yourself.

For this example, we’re going to use the Spotify API to demonstrate the different HTTP methods in action. Ready? Let’s go.

So how does all this help you in your role?

We’ve covered quite a lot there! But how can you apply all this in your role as a product manager?

Well, here are some things to consider, now that you know more about APIs than you did before:

• Opportunities – what are the opportunities for you and your product? How can APIs help you to achieve your goals? Is it worth running any ‘API appetite experiments’ to discover if a market for your APIs exists?
• API Audit – what APIs are currently being maintained but are not used? Can you bin any that are taking up development / maintenance effort?
• Confidence – can you now speak more fluidly about APIs with your engineering teams and your stakeholders about the opportunities and downsides to APIs? You can be more confident to prioritise API related features since you now have a basic knowledge of how they work and what the benefits might be for your product.

Congratulations. You’ve officially mastered the most useful things to know about APIs as a product manager. Now go and grab yourself a nutella sandwich.

Useful tools

Here are some useful API related tools for product managers:

• Apigee, a nice tool for APIs
• PAW, a great tool for use on the Mac
• Rested.io, a nifty website to enter API requests. Useful for accepting API related user stories.

Useful videos

• An Introduction to REST, by Google
• Basic concepts of web applications, by Natural Programmer
• Rest API tutorials