DEPARTMENT OF

PRODUCT

APIs
Explained
Make sense of API documentation, REST, GET, endpoints, headers and
payloads once and for all
departmentofproduct.com
10 things you should know
about APIs
Here’s what we believe are the most important things you need to know
about APIs as a product manager. Learn these concepts and you’ve got a
solid foundation to speak about APIs with confidence to stakeholders and
your team.

1. Requests and responses

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

I request something in a specific format as outlined in the API documenta-

tion 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 say-
ing, ‘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?

The basic characteristics of a RESTful API are:

• Resource based– in RESTful APIs we are dealing with ‘things’ or ‘re-

sources’. Nouns are the resources. A person, a user, a pdf, an address etc.
These are all known as resources.
• Representations – In RESTful APIs we deal with representations of re-
sources. If a resource is a noun, i.e. a thing, that noun can be represented
in various different ways. Using API calls, the response you get back is
a representation of the resource, transferred between the client and the
server. Most commonly in the JSON format. JSON is a language com-
monly used by REST APIs. XML is another representation of the same
resource.
• Six constraints – refers to constraints applied to RESTful architecture.
In order for a service to be truly RESTful, it needs to comply with the
following restraints.
• Uniform interface (Typically uses HTTP, resources, HTTP verbs as
the actions: GET, PUT, POST, DELETE)
• Stateless – each request has enough information for the server to pro-
cess the message.
• Client server – client server architecture. Always know that it’s a client
/ server connection, not a direct connection to the database for example.
• Cacheable – server responses must be cacheable
• Layered system
• Code on demand

Violating any of the principles or constraints outlines means that the ser-
vice is not strictly RESTful. You can no longer class yourself as a member of
the RESTful members club.
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 eas-
ier 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 poten-
tially 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 infor-
mation (CRUD is used as an acronym).

The most commonly used methods in our experience as a product person

are POST and GET, which allows you to create or read and retrieve infor-
mation. GET is straightforward and is considered the safest of all the meth-
ods since it doesn’t update any information.

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

POST

• Used to create new resources.

• For example, if we wanted to create a new text message using the Twilio
API, we would use the POST method since this is how you create new
resources (where the resource is the text message).

GET

• Used to read / retrieve a representation of a resource.

• When you perform the GET method, the response contains the infor-
mation you requested.
• GET requests are only used to read data and not change it. This means
they’re considered safe.
• For example, at Spotify, GET is used to retrieve a list of songs from an
album.

PUT

• Used to update / replace data.

• For example, updating a user’s email address.

DELETE

Self explanatory. Used to delete data.

There are others but we’re only going to focus on these since these are the
most common. If you know these, you know enough.

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.

Spotify API documentation

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

How the term ‘endpoint’ is used

• Hit – endpoints can be ‘hit which means we reach an endpoint to re-

quest a resource.
• Exposed – endpoints can also be ‘exposed’ which will allow resources to
be retrieved by others e.g. ‘we can expose an endpoint which will allow
an image of a barcode to be retrieved’.
• Call – ‘if we call the artists endpoint on Spotify we’ll retrieve a list of
artists’.

If we look back at our Spotify example, we’ve now added further informa-
tion including endpoints. Let’s understand how the endpoint is used…
Request
Spotify have ‘exposed’ an endpoint
called ‘Albums’ which we can hit.
Response
Spotify receives our request and
says
‘Hello there, I recognise that ID
you sent me, it’s the Spice Girls
album. Here’s the response,
which contains the album infor-
mation you requested. You lucky
thing.’

We hit the albums endpoint with a The response from Spotify con-
specific Album ID using the HTTP tains a bunch of information
GET method. about the resource i.e. the album.
This information includes
This tells Spotify, ‘hey, I want to re- (amongst other things):
trieve information for the album with
this ID: 123’. A link to the album art
A link to a preview snippet of the
If we’d used the HTTP DELETE meth- tracks
od, this would have meant we were Information about where the
asking to delete this album, which album was released
would have thrown an error since it’s The length of the track
unlikely we’d have relevant permis- This is known as a representation
sions from Spotify to be so destructive of the resource (the album). The
:). representation will typically be in
JSON format, which is a language
used by APIs.
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 API documentation

Twilio API documentation

The primary purpose of documentation is to lay down the rules of the ‘con-
tract’ 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 com-
monly 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 format-
ted
• 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 ex-
changes 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.

Some useful response codes to know

• 200 - success. Everything’s fine.

• 301 - the resource you’re looking for has been moved permanently.
• 400 - there’s a problem on the client side. The most famous error code is
 the 404 error. It means the server can’t map the request to a resource.
• 500 - there’s a problem on the server side.
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 re-
ceived 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 privi-
leges 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 au-

thorisation.
• Authentication – proves who you are
• Authorisation – defines the what you are permitted, or authorised to do
• Authentication usually includes:
• Username
• Password
• 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.

Useful tools and videos

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
• Postman - simple to use tool for PMs to make API requests
• 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
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 sand-
wich.
About us
The Department of Product is a global educational institution dedicated to
helping product managers and other technology professionals progress in
their careers through acquiring new skills.

Building digital products involves a unique blend of business, technology

and user experience and we know that excelling in all 3 of the areas can be
a difficult aspiration for most people. Our educational programs are de-
signed to help product managers and technology professionals improve in
areas they may be lacking and to enhance areas of excellence. Our programs
include:

• Product Mastery - designed for those looking to master essential prod-

uct development skills with an emphasis on developing product strategy,
roadmaps and business skills. You’ll learn both how to create a strong,
differentiated strategy and how to execute your strategy, using leading
product companies as case studies.
• Web Technologies - designed specifically to help you get to grips with the
technical aspects of product development and working with engineering
teams. You’ll learn about front end development technologies, program-
ming languages, APIs, databases and github - all from a management
perspective.

To be a product person means to never stop learning.

DEPARTMENTOFPRODUCT.COM