https://www.departmentofproduct.

com/blog/apis-explained-for-product-managers/

https://danielelizalde.com/the-business-of-apis-what-product-managers-need-to-plan-for/

REST - HTTP, SOAP, GRAPHQL

AUTHENTICATION - TOKEN VIA COOKIE ON WEB BROWSER AFTER USER SESSION;
TIMELINE - PAGINATION,
RATE LIMITING - USER BY USER BASIS, TIME LIMIT; UNUSUAL SPIKES - IP ADDRESS BAN

How do APIs work? An abstraction

Let’s use a metaphor to explain how an API works.

Imagine you’re a customer at a restaurant. The waiter (the API) functions as an intermediary between
customers like you (the user) and the kitchen (web server). You tell the waiter your order (API call), and
the waiter requests it from the kitchen. Finally, the waiter will provide you with what you ordered.
The waiter is the intermediary between you and the kitchen. In this metaphor, the waiter is effectively
an abstraction of the API. In software engineering, an abstraction is a fundamental concept that aims to
simplify a complex mechanism by only focusing on the details of higher importance. In this example, as a
customer, you don’t need to know how the kitchen or the restaurant operates in order to get what you
want: the food. You just need to know how to order it.
In most API requests, there are often a few key pieces of information:
• Type of request

• Authorization credentials (to prevent mimicked API calls from any attacks on the server)

Types of APIs
The most common discussion you’ll hear about APIs tends to focus on web technologies, but APIs aren’t
limited to web services. Here’s a roundup of common (and not so common) APIs.

REST APIs If you’ve heard people talk about JSON (javascript object notation), chances are they’re
talking about REST APIs. Over 70% of all public APIs use REST, because of its fast performance, reliability,
and ability to scale by reusing modular components without affecting the system as a whole.

How do REST APIs work? REST, or “representational state transfer,” is a type of software design that
gives access to data (aka “web resources”) by using a uniform and predefined set of operations. The
payload - the data to be delivered - defined in the request itself, will be formatted in a language such as
HTML, JSON, or XML. The set of operations are the methods available to HTTP, which is the underlying
protocol for how browsers retrieve websites from servers. These methods include GET, POST, PUT,
DELETE, and others.
There are four parts of a REST API request:
• URI (uniform resource identifier, which is the URL address, also known as an “endpoint”)

• HTTP method (most commonly either GET or POST)

• Headers (which include authentication tokens, define the data format of the response, impose
rate limits, and perform other administrative tasks)
• Body (the actual part of the request)

SOAP APIs SOAP, or “Simple Object Access Protocol,” is a bit more complex than REST because it
requires more information upfront about security and how it sends messages. These additional
standards require more overhead, and as a result, SOAP - an API standard that has been around since
the late 1990s - tends to lack the lightweight portability and flexibility of REST.
Browser APIs A browser is capable of creating a wide variety of user experiences, such as playing music,
displaying intricate animations, and reacting to mouse or keyboard input. A browser gives control of
these experiences to web developers via browser APIs using javascript to manipulate the HTML or
create unique experiences within a browser instance.
iOS/Android APIs Similar to browser APIs, each mobile platform has its own set of APIs that provides
developers the tools to build experiences for their end users. App developers can use these APIs to
transmit data to the device’s hardware, use a sensor from the hardware such as a camera, play music or
video, or perform many other capabilities.

Each of the products indicated by the red boxes exposes an API that is consumed by the team building
the eCommerce site. The Product Managers building those third-party products made a business
decision to open their API. They had a strategy on how it was going to be consumed and the value it
would bring to their users.
The Business Advantages of Exposing an API
#1 An API allows your customers to innovate at their own pace.
No matter how fast you release new features, you’ll never be able to meet the needs of every single
customer. Having an API gives your customers (and their development partners) the freedom to
customize your software and build the exact solution they need today, not six months from now when
you release the next version of your software.
If your product is targeted towards mid and enterprise markets, then having this ability is a must. Your
product strategy needs to inform which APIs you need to build first, so you can expose the most critical
functionality as soon as possible.
#2 Having an API enables professional services revenue.
If your customer is looking for a feature you don’t have or needs specific customizations, having an API
can help you close the deal and bring in additional revenue in the form of professional services. In
Enterprise software, it is very common to have an implementation team that focuses on developing
one-off features for specific clients. This also helps keep your core development team focused on
developing strategic features that will solve problems for your critical mass of users.
#3 With an API, you can build a partner network.
While your Sales team is finite, a partner network can bring scalability and additional revenue to your
organization. Once you have an API, partners can either integrate into your product (like the
eCommerce example above) or they can build custom tools and functionality on top of your product.
The key advantage here is that partners will help you sell your product because they want to sell their
products or services on top of it. By creating a partner network to leverage your API, you have
automatically created new sales channels and have scaled your Sales and Marketing teams in a way that
otherwise might not be possible.
Just like any product, an open API needs a business justification, user personas, clear use cases, a
roadmap, a revenue model, a pre- and post-launch plan, and specific needs in the areas of marketing,
sales, support, documentation, and security. These needs are completely separate from those of your
core product, though they should be strategically consistent. In fact, it’s not unusual for companies to
assign a dedicated Technical Product Manager to their API and partner/develop
community. Engineering will provide a lot of input, but the overall approach and functionality should be
owned by the Product Manager.
Open APIs are one of those situations where “with great power, comes great responsibility.” It brings a
lot of new challenges, and as a Product Manager, you need to be able to sell the value to the
organization and make sure they understand everything that it takes to make it successful. You also
need to be able to walk away when it’s not the right decision for your product, or maybe just not the
right time to tackle it yet.
#1 Realize how different the “Developer persona” is from your existing users
Congratulations! You’ve just added a new user persona: Developer. And this persona is radically
different from your core product’s business users. Even if their domain knowledge is similar (i.e. both
work in CRM or consumer electronics companies), their tools, objectives, and views of the world are
very different from each other.
Focus on “Developer Experience”, meaning that your product needs to provide usability paradigms that
align with that persona. For example, most developers prefer using an SDK (software development kit)
as opposed to coding directly against the API. Providing SDKs in their programming language of choice
decreases ramp-up time and allows companies to leverage the training and tooling investments they
already have on a particular technology. Other developer experience areas include having a
good documentation, good tools, and a strong community.
When building a very technical product for a very technical audience, I do recommend recruiting
a Technical Product Manager to lead the effort. The TPM won’t code or design the solution. Instead,
she brings a deep understanding of this audience and will be able to navigate it more quickly.
#2 How will you increase your product’s revenue by building an API?
Opening an API can be a big investment. So how will you make money out of it? How will your product
and company be better off after this investment? There are many ways to approach this, but here are a
few possible paths to capitalizing on your API.
• Charge for access. Monetize the API itself by charging for API usage. This approach has worked
great for companies like DropBox, but keep in mind that in order to do this, you’ll need to build
all the tracking mechanisms as well.
 • Improve sales conversion. Increase revenue of your core product because the API makes it
more attractive and easy to sell.
• Sell professional services. This requires the creation of a professional services team, but if done
correctly, the margins can be really good.
• Sell applications. Use the API as a platform to build new components which you can sell for
additional revenue through an app marketplace. Or charge a markup on apps built by others
and sold in your marketplace. Or both!
#3 Be ready for a significant increase in operating expenses.
Consider this. If your current product targets users in Sales roles, and now you add a new product
module for Marketing professionals, then it is very likely that your current staff will be able to support
this new user type. Your Sales team can still pitch to the CMO, your Marketing team can create the
messaging, your Technical Writers can write product documentation, and your Support team will still be
able to answer their questions.
In contrast, when you add a user of type “Developer” into the mix, you probably will need to add
technical people to your existing staff, as well as conduct training across all teams to ensure they
understand the Developer persona. That’s why from my point a view:

Basics of APIs
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.
In this example, you can see how a basic webpage is rendered.
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.
The 10 most important things to know about APIs
1. Requests and responses
 2. REST
3. HTTP methods
4. Endpoints
5. API documentation
6. API calls
7. Payloads
8. Response codes
9. Headers
10. Authentication
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.
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?
The basic characteristics of a RESTful API are:
1. Resource based– in RESTful APIs we are dealing with ‘things’ or ‘resources’. Nouns are the
resources. A person, a user, a pdf, an address etc. These are all known as resources.
2. Representations – In RESTful APIs we deal with representations of resources. 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 commonly used by REST
APIs. XML is another representation of the same resource.
3. 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.
1. Uniform interface (Typically uses HTTP, resources, HTTP verbs as the actions: GET, PUT,
POST, DELETE)
2. Stateless – each request has enough information for the server to process the message.
3. Client server – client server architecture. Always know that it’s a client / server
connection, not a direct connection to the database for example.
4. Cacheable – server responses must be cacheable
5. Layered system
6. Code on demand
Violating any of the principles or constraints outlines means that the service 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 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:
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 information 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.

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 request 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 information including endpoints. Let’s
understand how the endpoint is used…
Popular Posts
• Writing BDD Test Scenarios

• APIs Explained for Product Managers

• Metrics that Matter to Product Managers

• 5 Useful Diagrams for Product Managers

• Product Monetization Strategies

Recent posts
• Component Oriented Thinking for Product Managers

• 5 Ways to use Post it Notes as a Product Manager

• How to Agree Ways of Working as a Product Team

• Radical product strategy

• How to measure product market fit

Subscribe for updates

Programs
• Web Technologies Program

• Product Mastery Program

Resources
• Product Roadmaps

• Product Strategy

• Product Guides

Search
Request Response

Spotify have ‘exposed’ an endpoint called ‘Albums’ Spotify receives our request and says
which we can hit.
‘Hello there, I recognise that ID you sent me,
We hit the albums endpoint with a specific Album ID it’s the Spice Girls album. Here’s the response,
using the HTTP GET method. which contains the album information you
requested. You lucky thing.’
The response from Spotify contains a bunch of
This tells Spotify, ‘hey, I want to retrieve information
information about the resource i.e. the album.
for the album with this ID: 123’.
This information includes (amongst other
If we’d used the HTTP DELETE method, this would things):
have meant we were asking to delete this album,
which would have thrown an error since it’s unlikely • A link to the album art
we’d have relevant permissions from Spotify to be so
• A link to a preview snippet of the tracks
destructive :).
• Information about where the album
was released
• The length of the track
This is known as a representation 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 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.
Some useful response codes to know

HTTP response Meaning

code

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 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.
Example 1 – POST
Using the HTTP POST method, we’ll add tracks to a playlist.

In order to design an API with a great UX, you should answer these questions while designing it:
1. Useful: Is the API useful from an end user’s point of view?
2. Usable: Can the API be quickly used by a developer and provide easy-to-use functionality?
3. Desirable: Is the functionality provided by the API something that generates desire in
developers and end users?
4. Findable: Can the API documentation be found easily, and can developers start using it
immediately?
5. Accessible: Can the API provide functionality for end users who have technical
constraints/limitations in consuming it?
6. Credible: Is the data provided by the API trustworthy?
7. Valuable: Does the API contribute to the company’s bottom line and improve customer
satisfaction?
Defining a Design Process for APIs
The strength of a design lies as much in the steps taken to create it as in the final result. A design
process helps you to remain transparent and efficient while designing a solution. It sets a clear
expectation and decreases the risk of delivering unwanted results.
The Double Diamond design process by the British Design Council is one of such many design processes.
It allows people to make intentional design decisions by exploring various options (divergent thinking)
while validating stronger ones and weeding out the weaker ones (convergent thinking).
The Double Diamond design process
This approach will help you in achieving two of the most important things in any design process:
Designing the Right Thing
Designing the Thing Right
Designing the Right Thing
This phase is split into Discover/Research and Define/Synthesis. While designing something new it is
very easy for people to blow the actual scope of the problem and put all their effort into designing
something that no one actually wants or will use. This phase of designing keeps us grounded and makes
sure we are designing for the right thing by doing diligent research and defining the right problem
statement to solve.
Discover/Research: When you are building a new Product, Feature or an API you are trying to solve a
problem. In order to provide a solution, you need to first understand the problem. Always start by
acquiring the Domain Knowledge about the problem. Try to understand what problem you are trying to
solve, who is this being built for etc. Clarify on the use-cases and the requirements. Research on existing
solutions to understand how they are solving the same problem and what you can learn from their
architectural/technical decisions. Talk to all the teams inside/outside your organization that are
stakeholders for this new API which might include Product Team, Design Team, Security Team, etc. Their
different perspective will give you a broader view to think about your API and the technical decisions
that you are planning to take from that point onwards.
You can also leverage the Postman API Network for your research or reference to find out how different
organization’s APIs looks like. Postman’s API Network contains a diverse list of APIs which are published
by organizations from a lot of different domains and industries. For example, if you are building the API
in FinTech space, for your research you can check some of the APIs published by other organizations in
the Financial Services section.
Develop/Ideation: Once you are clear on ‘what needs to achieved’ using APIs, it’s time to design those
APIs so that you can communicate on what you as API provider intent to ship. API Description Languages
such as OpenAPI/Swagger, RAML, etc are a great way to express important aspects of an API. Especially
the frontend design decisions and architectural design decisions, which are visible to the consumer, can
be captured by API description languages. But one drawback with these API description languages is that
they can get way too technical, verbose and difficult to collaborate upon. So alternatively what you can
do is import Swagger, OpenAPI or RAML specification files into Postman Collection.
If you have worked closely with a UX/Design team before you would have noticed that some of the
outcomes at the end of their designing process are documentation around all the features and
interactions, representation of various states of UI (error states, empty states, etc) and a prototype
which demonstrates the exact interaction with the UI and what should be the expected outcome.
Using Postman collections you can also achieve the same outcome for your APIs and provide total
transparency to all the stakeholders around it.
• API Documentation: You can document your collection, folders, requests, up to the granularity
of documenting headers, query parameters, etc in the request. Along with this, Postman
also generates beautiful looking documentation out of the box which can be shared with
anyone.
 • Different API scenarios/states: You can design different Examples for every API so that
consumer knows what request to send and what response to expect. Generally, it’s
recommended that you add examples for all different request/response scenarios possible for
the API, including error responses, empty responses, etc.
• Prototype: You can create a Mock server that will return the designed examples as a response.
This is very helpful because it immediately enables your API consumers and they can start
prototyping /testing their use cases even though the actual API is not ready.
Deliver/Implementation: After you have successfully designed your APIs now is the time to start
implementation. But before you start coding your APIs you should establish a Contract Test for your API
which will ensure that if anything changes during development in the agreed API request/response
design, these Contact tests will start failing. Then you can either update your code or inform all the
affected teams. Also, it is very easy in Postman to collaborate with your entire team. You can constantly
receive feedback using comments while you are actually developing your APIs and any changes that you
make will instantly be made available to everyone involved in the process.
Building a Design Style Guide, but for APIs
When you are working in a growing team with new people joining in every now and then, after a certain
point of time it becomes very difficult to ensure the quality, consistency, and security of the APIs.
Imagine what would happen if every new developer will start following their own convention of naming
endpoints, using Authorization, headers query parameters, success and error response structure, etc
while developing an API.
Design teams face a similar challenge when creating a new UI. They solve this by building Design Style
Guides which make sure that everyone in the team uses the same UI component, colors, typography,
etc. Using Design Style Guide it becomes easy to communicate between teams, keep UI consistent in the
long term and bring agility in the design and development processes.
So, why not have a Design Style Guide for APIs itself? Companies like Google, Microsoft, Cisco, Paypal,
and many more rely on these API Styleguides to make sure their APIs remain consistent, look cohesive
and intuitive. The benefits of consistency accrue in aggregate as well; consistency allows teams to
leverage common code, patterns, documentation and design decisions. It will also ensure to make the
developer experience as smooth as possible, for both API producer and consumer. Some of the
important things that should be part of an API Style Guide are:
URL Structure: How should a URL format for a given resource look like, what should be the path, query
parameters, etc.
Request methods: Define a list of request method and define when to use which request method. This
will make sure that request methods have the same behavior across your APIs.
Request/Response Headers: List of headers that should be used with the API while requesting to service
and responding back.
Response status codes: Create a list of allowed status codes for your API and clearly set the guidelines
on when to use a specific status code.
Errors: Design a common error response format that all other developers can use. A good error
response should let a developer recognize, diagnose and recover from errors.
Versioning: Establish guidelines on how to version an API and points to keep in mind while versioning an
API.
Filtering/Pagination/Sorting: How to support filtering and pagination in your APIs which returns a
collection of data, what should the response JSON look like with filtered/paginated/sorted result.
To help people quickly get started, I have published a collection as a template that you can import and
start fiddling around.