Skip to Content

My Home
Course Menu
Get Unstuck
Tools

Introduction to the API Development

Lifecycle
Learn about the various stages of API development!

The contents of this article were originally posted by SmartBear. SmartBear is

a software quality company offering tools for teams to better design, develop,
and test their software at scale. You can learn more by visiting SmartBear’s
blog and read the original article What is API Lifecycle Management? by
Keshav Vasudevan.

What is the API development lifecycle?

Application Programming Interfaces, or APIs, have become a vital tool for
both engineers and businesses as a whole. APIs enable two different
services to interact and complement each other, opening the doors to many
engineering and business possibilities.

However, developing an API by itself is no easy task. Creating an API

encompasses a series of steps, each with its own complex processes. This
collection of steps is known as the API development lifecycle. To understand
how to develop successful APIs, we must first understand each stage of the
lifecycle.

While there are many frameworks and methodologies for the API lifecycle,
there are typically five chronological stages:
 1. Planning and Designing the API
2. Developing the API
3. Testing the API
4. Deploying and Managing the API
5. Retiring the API

Each of these stages is a vital piece to making sure an API is successful. Let’s
dive in and explore the details of each stage.

Planning and Designing the API

API planning and design is the first stage of the API development lifecycle.
This stage involves ideating and mapping out the various resources and
operations and their associated use cases before the API is fully
implemented in code.

Typically business team members (or sometimes even engineers) will begin
by mapping out the capabilities of the API and the data it should expose.
This process usually captures the API audience’s needs and the
requirements from various stakeholders.

When the API requirements are done being mapped out, engineering teams
can then begin laying out the architecture of the API. Naming conventions,
protocols, technology, and much more are debated and finalized.

Developing the API

Once the requirements are mapped out and the engineering team has a
plan, the development stage begins. This stage focuses on implementing
the API based on the plan and design and is when engineering teams will
do the necessary work to bring the API to life.

Typically this is also where the API is documented. Often when APIs are
treated as a product (that the team or business makes revenue from), teams
will spend just as much time documenting their API as they will on any of
the other phases. A good example is the IMDB Movie API that offers free
and paid services. Note the extent of the APIs documentation found here.

Testing the API

In the testing phase, the API would be thoroughly tested and monitored for
performance issues. This phase typically catches any issues so that
engineering teams can refine the API before it is released to the end-
users (sometimes referred to as end-consumers) — the person or persons
who will use the product (e.g., the API).

Deploying and Managing the API

Ultimately, APIs must satisfy a use case for an end consumer, be it an
internal developer team, a partner company, or the general public. After the
testing phase, APIs are ready for release and are deployed to a secure
environment to facilitate easy discovery and consumption.

On some occasions, mainly when APIs are public-facing, APIs are released
into beta where end-users (sometimes only a small percentage) can test and
experiment with the API and give feedback and report bugs. The beta helps
finalize any outstanding issues as well as gain valuable feedback before a
full API release.

This phase is also where APIs are managed for the rest of their lifetime to
deliver guaranteed and high-quality API performance. Management
includes but is not limited to performance tracking, usage analysis,
community building, and a lot more!

Retiring the API

Lastly, the final phase of the API lifecycle is deprecation. This phase is where
support for an API’s version, or in many cases, an entire API itself, is
discontinued.

Deprecation involves creating a detailed plan on migrating users away from

the API and releasing the APIs resources. Deprecation needs to be handled
with extreme care as it may impact many end-users and associated
products that utilize the API.

Wrap up
To summarize, we learned:

 What the API development lifecycle is

  What happens during the API design and planning phase
 What happens during the API development and management phase
 What happens during the API testing phase
 What happens during the API deployment phase
 What happens during the API retirement phase

Learning to master the intricate processes in each stage of the API

development lifecycle will bring us and the teams we work on closer to
implementing successful API solutions.
Back
Next

API design is the process to develop application programming interfaces,

where the data and application functionality is used by developers and
users.

API design is the process to develop application programming interfaces,

where the data and application functionality is used by developers and
users.

Skip to Content

My Home

Course Menu

Get Unstuck

Tools

API Design Guide

Learn about what API design is, the benefits of investing in it, and
some best practices for designing your own API.

The contents of this article were originally posted by SmartBear. SmartBear is

a software quality company offering tools for teams to better design, develop,
and test their software at scale. You can learn more by visiting SmartBear’s
blog and read the original articles What is API Design (and why does it
matter?) and Best Practices in API Design by Keshav Vasudevan.

Defining API design and why it matters

Building successful APIs is difficult. Apart from the various stakeholders
(engineers, designers, etc.) and technology decisions, there are a lot of finer
details that can get overlooked. One slip-up can result in endless support
requests from end-users and eventually result in a bad reputation. It’s
crucial to plan, plan, and plan even more before actually implementing an
API. This is why API design, typically the first step in the API development
lifecycle, is so important.

API design is defined as the iterative collection of decisions that lead to a

concrete plan for developing, implementing, and maintaining an API. The
design process is not just about the developers who are building the API
but also about understanding the API’s end-user, their needs, and how best
the API can meet those needs. There are notable benefits in investing time
and resources into the design phase of the API development lifecycle. Some
of the benefits include:

 Effective Implementation: A detailed API design can significantly

help in the APIs implementation (usually by developers) phase by
preventing ambiguity.
 Incremental Development: Having a straightforward design helps
know precisely which resource, or sub-resources, would need to be
updated (or retired), preventing confusion and leading to less
duplicated work.
 Better Documentation: A solid initial API design makes documenting
the API faster and less error-prone.
But how exactly do we know we have created a well-designed API? Let’s
explore a few characteristics most well-designed APIs share.
Characteristics of a Well-Designed API
Typically, a well-designed API will have the following characteristics:

 Easy to read and work with: A well-designed API will be easy to

work with, and its resources and associated operations can quickly be
memorized by developers who work with it regularly.
 Hard to misuse: Implementing and integrating with a well-designed
API will be a straightforward process and less error-prone. It has
informative feedback and doesn’t enforce strict guidelines on the
API’s end-user.
 Complete and concise: A well-designed API is a complete API. This
means the API exposes any data that the end-user expects it to
expose. Most APIs are completed over a long period of time –
implementing end-user feedback and releasing new versions along
the way.
 Well documented: Finding any information about endpoints,
integrations, and features should be simple with a well-designed API.
The documentation will cover and explain all the available
functionality of the API.
 Reliable: An API’s end-user will depend on an API to be available and
functioning when they need it. They also expect functionality to not
arbitrarily change without any proper notice.
But how do we make sure our APIs have these characteristics? Well, let’s go
through some standard, applicable best practices to create and maintain a
well-designed API. By doing so, we will see how small changes in our APIs
design can help bring us closer to achieving the characteristics listed above.

Before we dive in, let’s imagine a hypothetical photo-sharing application.

The application allows end-users to upload photos, characterizing them by
the location of where the photos were taken. End-users can also hashtag
the photo to describe the emotions associated with them. Keep this
application in mind as we will explore the best practices of three distinct
parts of an APIs design:

 Collections, Resources, and Their URLs

 Requests
  Responses

Before moving on, let’s review:

Free response

In your own words, what is API design?

Your response

API design is the process to develop application programming interfaces,

where the data and application functionality is used by developers and
users.
Our answer

API design is defined as the iterative collection of decisions that leads to a

concrete plan for developing, implementing, and maintaining an API.
Typically this is the first step in the API development lifecycle.
  Edit Response

Collections, Resources, and Their URLs

Nouns are Your Best Friend
For any resource or collection that represents some data in an API, the base
URL should always be neat, elegant, and, most importantly, intuitive. A long
and difficult-to-read base URL is not just bad to look at but can also provide
a more error-prone and challenging experience for the end-user. For
example, let’s take a look at a set of potential URLs (and associated HTTP
verbs) for our previously mentioned photo-sharing application:

API Route Purpose

/retrieveEveryPhoto Retrieve all photos

/getSinglePhoto/1 Retrieve a single photo

While these API URLs might seem easy to comprehend, it’s easy to imagine
our URLs getting very lengthy and confusing in the future. There is also no
clear consistency between what and how each of the resources is called (ex.
“get” vs. “retrieve”). This is why it is best to keep API URLs consistent by only
using nouns. Here are the same API resources re-written with a single noun:

API Route Purpose

/photos Retrieve all photos GET

 API Route Purpose

/photos/1 Retrieve a single photo GET

There’s no hard rule on keeping the resource nouns singular or plural,

though having the same plurality across all resources and collections helps
achieve a level of consistency.

Describe resource functionality with HTTP methods

Recall, RESTful APIs are comprised majorly of HTTP methods that have well-
defined and unique actions for any resource. These methods help all APIs
achieve a level of consistency in the type of operations end-users expect to
occur when using an HTTP method. For example, here’s a list of commonly
used HTTP methods that define the CRUD operations for any resource or
collection in our photo-sharing app:

HTTP Verb Description Exam

GET Retrieve a resource GET /photos/1

POST Add a resource POST /photos

PUT Update a resource PUT /photos/34

PATCH Update a resource PATCH /photos/4

DELETE Delete a resource DELETE /photos/12

Mapping these HTTP methods to describe the typical CRUD operations of

our applications allows developers to know exactly what they should expect
to occur.

Responses
Give Feedback to Help Developers Succeed
Providing good feedback to developers on how well they are using an API
goes a long way in improving adoption and retention. Good feedback
involves positive validation on correct implementations and an informative
error on incorrect implementations that can help developers debug and
correct how they use the API.

For APIs, errors (and relevant error codes) are a great way to provide
context when things go wrong! In general, there are three possible error
outcomes when using an API:
 1. The client application behaved erroneously (client error - 4xx
response code)

2. The API behaved erroneously (server error - 5xx response code)

3. The client and API worked (success - 2xx response code)

When designing an API, describe these error responses well, but keep them
concise and neat. In addition, use specific response codes to detail errors
accordingly in the API (check out this great resource on error codes). Lastly,
provide enough information in the error codes for an end-user to start work
on fixing the cause, and, if there’s more information needed, provide links
to additional documentation.

Requests
Handle complex requests elegantly
An API should be able to access many different types of data, so we want to
be mindful of organizing it to best help our end-user. We want to make
sure that our data is complete, available, and accounts for relationships
between different types of data. In the interest of performance, we’d only
want to surface the relevant data that an end-user needs and even consider
limiting the amount of data they get in the response.

We’ve already seen how we can retrieve individual resources (e.g. /photos/1)

and a collection (e.g. /photos), but how can we add more complex behavior to
our requests? One way to account for specific properties and limit
responses is to use a query parameter, adding a ? with key-value pairs that
list out what a user needs.
Let’s take the example of our photo-sharing app. Someone might want to
get photos from a specific location and a specific hashtag. We might also
want to limit the number of results to 10 per API call to prevent server load.
If the user wants to find the top 10 photos in Boston with a hashtag #winter,
the call would be:
GET /photos?location=boston&hashtag=winter&limit=10
Notice how the complexities have now been reduced to a simple
association with a query parameter. These are just some of the ways we
could design parameters that strive towards API completion and help our
end developers use our API intuitively.
Also, when in doubt, leave it out. Developing and maintaining APIs is a
continuous process, so we can wait for feedback from our end-users to see
how we can improve our API. This way, we account for the immediate and
future needs of the API.

Before wrapping up, let’s review:

Wrap up
To summarize, we learned:

 What API design is and the benefits of investing in it

 Common characteristics of a well-designed API

 Common best practices when approaching API resource naming,

requests, and responses

There isn’t a single approach to API design that will work for every
individual or organization. The above suggestions are just that — advice
and recommendations which can be used or discarded depending on our
end-users needs.
Back

Next

Skip to Content
My Home
Course Menu
Get Unstuck
Tools

Introduction to API Documentation

What is API documentation, why does it matter, and what are the
benefits of creating it?

This article was originally posted by SmartBear. SmartBear is a software

quality company offering tools for teams to better design, develop, and test
their software at scale. You can learn more by visiting SmartBear’s blog, and
you can also read the original article What is API Documentation, and Why It
Matters? by Keshav Vasudevan.

Defining API Documentation

APIs can provide a lot of value internally to a company and also externally
to end-users. However, for an API to be valuable, it must be easy to
understand. This is where API documentation comes into the picture.

API documentation is technical content containing instructions about how

to effectively use and integrate with an API. It’s a concise reference manual
containing all the information required to work with the API.
Documentation typically includes tutorials with examples and details about
the functions, classes, return types, arguments, and much more. API
Documentation is traditionally created using regular content creation (e.g.,
text editors) and maintenance tools.

Among all the phases in the API lifecycle, documentation is the area
showing the most growth. This is especially true with the tooling ecosystem
around documentation. Since documentation is traditionally something that
fell on the backburner for development teams, it also means that there’s a
lot of room for growth. We can have the best functional API, but no one will
use it if they don’t know how to.

Before we continue, lets review:

Benefits of Well-Crafted API Documentation

So, what exactly do we gain by investing in API documentation? Well, some
benefits include:

 Improved End-User Adoption: Adoption patterns are already

shifting towards developers in the technology sphere. One big reason
for having good API documentation is that it improves the experience
 for developers using the API, which directly correlates with API
adoption. People adopt APIs they enjoy using, and if we get
documentation right, more people will find value in the services easily,
leading to better growth and adoption.
 Improved Developer Experience (DX): The third-party developer,
typically one of many end-users for an API, is busy solving complex
programming challenges. These developers want to integrate as
quickly as possible to move forward in their software development,
meaning they should immediately understand the value and usage of
the API. The aggregate experience of the developer when discovering,
learning to use, and finally integrating with an API is termed
as developer experience (DX) — and excellent API documentation is
the key to a great DX.
 Increased Awareness: Satisfied end-users will be an APIs biggest
advocates. As more end-users adopt an API and reach critical mass,
there will be a probable increase in evangelism and word-of-mouth
publicity by satisfied end-users.
 Saves Support Time and Costs: In addition to driving increased
awareness and adoption of an API, good documentation also
decreases the amount of time spent onboarding new end-users, be it
internal developers or external partners. Poor or no documentation
means more frustrated users rely on a team to understand how to
work with the API. In contrast, individuals and teams save countless
hours responding to support requests when end-users are given the
ability to try out the API before implementing it and are armed with
detailed documentation to get started.
 Easier Maintenance: Documentation leads to good API maintenance.
It helps internal teams know the details of an API’s resources,
methods, and their associated requests and responses, making
maintenance and updates quicker.
Before we warp up, lets review:

Wrap up
To summarize, we learned:

 What API documentation is

 What Developer Experience (DX) is
 The benefits of investing in a well-crafted API documentation
Documentation is the key to a great experience when consuming an API. It
not only enables end-user satisfaction but also allows API adoption to
increase.

Skip to Content

My Home

Course Menu

Get Unstuck

Tools

API Documentation Best Practices

Learn how to write great documentation for an API.

The contents of this article were originally posted by SmartBear. SmartBear is

a software quality company offering tools for teams to better design, develop,
and test their software at scale. You can learn more by visiting SmartBear’s
blog, and you can also read the original article Best Practices in API
Documentation by Keshav Vasudevan.

Introduction
APIs are only as good as their documentation — a great API can be
rendered useless if people don’t know how to use it. However, creating and
maintaining good documentation that’s easy to read, enjoyable to interact
with, and sets the end-user up for success, can be extremely challenging.
Creating excellent documentation requires effort and patience, but it has
direct implications for API adoption and maintainability. In this article, we’ll
start by looking at who we should design documentation for and then
follow up with exploring some common best practices. Let’s dive in!

Who is the API documentation for?

Most likely, an API is meant to solve real-world problems faced by
companies in a specific industry and will directly be integrated into
applications by software engineers. As such, there are two types of potential
audiences of an API who will influence an API’s consumption and its
adoption usage:

 Decision-makers: Decision-makers are the people who evaluate an

APIs services and decide if it makes sense for the development team
to spend time exploring the service. They are looking to use an API to
solve potential challenges in their product or service strategy. In many
cases, they don’t directly work with the API, but they are the main
points of contact for influencing an organization’s decision to
consume it. Examples of decision-makers are CTOs or Product
Managers.
 Users: Users are the people who will be directly working with an API.
They need to learn the ins and outs of the API and how it applies to
their use case. This could mean learning how to call and integrate
with many, or all, of the resources the API exposes. They are critical to
the sustainability of an API. They are analytical, work on significant
and complex engineering problems, and have a shortage of time.
Hence, an API must be easy to use and have excellent documentation
so these users can successfully integrate with an API as quickly as
possible. Examples of API users are front-end and back-end
developers.
Ideally, an API’s documentation needs to cater to both personas. This can
be challenging, but it ensures the documentation is sustainable and
complete, ensuring long-term success. So, how do we accomplish these
goals and serve both user groups? Well, let’s run through some common
best practices that will set up our next API documentation for success!

Before we move on, let’s review:

Multiple choice

Who should the API documentation be written for?

Non-technical users such as clients and managers
Neither technical nor non-technical users
Technical users such as developers and testers
(Selected)Correct:

Both technical and non-technical users

👏
Good Job! You got it right! Technical users (such as developers) and non-
technical users (such as clients) both need to understand the
documentation.

Best Practices in API Documentation

Now that we’ve understood who to document APIs for, it’s time to
understand what goes into good API documentation. Let’s dive into some
best practices all well-documented APIs follow!
Detailed Error Messages
Error messages are important because they tell end-users when they’re
integrating with an API incorrectly. Explain error standards and provide
solutions on how to overcome them when an end-user gets an error.

A List of All Exposed Resources

Resources are the core components of an API that end-users will constantly
be interacting with. An API should list all of its exposed resources and
understand how end-users may integrate with them.

A Terms of Use Agreement

Terms of use is a legal agreement between the end-user and an
organization, defining how the end-user should ideally use the API’s
services. These terms should include API limits under best practices, with
terms and conditions. Constraints also need to be clearly stated so that end-
users understand what API usage and practices are permitted, so they don’t
accidentally have their access restricted.

A Changelog
A changelog is a document, usually published on an APIs website, that
should detail updates and versions of an API and how it might affect API
end-users. This will help end-users know the stability of the API and see if
any changes need to be made to their integration with the API.

Less Technical Jargon

Keep in mind that many end-users working with an API may not have
intimate knowledge of the domain to understand technical jargon.
Documentation should cater to the “very technical” developer audience and
the less technical decision-makers. A big mistake technical writing teams
make is assuming their audience is entirely technical and has a complete
understanding of how to work with APIs. If an API does have technical or
domain-specific jargon, it is helpful to link those specific items to further
documentation explaining the terms.

Examples of all Requests and Responses

An API call response is a guide for end-users, indicating whether they’re on
the right track or are doing something wrong. An API end-user should know
exactly what to expect from a successful API call. Ideally, an API provides
examples for every single object it is supposed to return and examples of
parameters that end-users can add for a successful call.
It is also best to describe the entire sample response body in every
supported format. Think of standard formats like XML or JSON, but also
HTTP headers, error codes, and messages.

An Authentication Guide
An API’s documentation should have a section dedicated to any
authentication (if it exists) required to start consuming the API’s data. Most
APIs have authentication schemes, and end-users have to authenticate
before gaining access to the API. Make sure this section is adequately
documented and hand-holds end-users to authenticate against the API
successfully.

Arm Documentation with Resources

Excellent API documentation goes beyond the essential content and
ensures end-users reach success with an API as quickly as possible. Let’s
examine some potential candidates for resources to include in the
documentation.

A Getting Started Guide

The getting started guide provides a detailed account of how to start
working with the API quickly. The emphasis in the guide should be on
ensuring end-users reach success with the API as soon as possible, hand-
holding them throughout the journey.

SDKs and Libraries

Code libraries help developers quickly call different resources. Having quick
and easy methods in different languages to work with an API allows
developers to feel more comfortable working with it. Software Development
Kits (SDKs) - a set of libraries or tools that end-users can work with out of
the box, are challenging to build, and aren’t crucial for launch, but can
significantly improve API adoption.

A Interactive Console
One way to encourage end-users to test what they read in the API
documentation immediately, is to provide an interactive API console.
Experimentation is powerful, and a console makes getting started easy, with
limited liability from the end-users perspective. An interactive console can
go a long way in helping developers learn about an API’s value very quickly.
Before we wrap up, let’s review:

Free response

In your own words, describe the importance of excellent API

documentation.

Submit Response

Stuck? Get a Hint

Wrap up
To summarize, we learned:

 The two types of people API documentation is typically written for

 A few best practices to follow when writing API documentation

 Key resources that API documentation should provide

Although it may seem challenging and time-consuming, following these

practices and creating these resources will help make excellent API
documentation that is effective and helpful to all individuals who use it.
Back

Next

6 days left to meet your weekly target. Keep up the good work!
M
T
W
T
S
S
1 / 7 days