Professional Documents
Culture Documents
Building An Api Product Design Implement and Release Api Products That Meet User Needs Pedro Full Chapter
Building An Api Product Design Implement and Release Api Products That Meet User Needs Pedro Full Chapter
All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or
transmitted in any form or by any means, without the prior written permission of the publisher,
except in the case of brief quotations embedded in critical articles or reviews.
Every effort has been made in the preparation of this book to ensure the accuracy of the information
presented. However, the information contained in this book is sold without warranty, either express or
implied. Neither the author, nor Packt Publishing or its dealers and distributors, will be held liable for
any damages caused or alleged to have been caused directly or indirectly by this book.
Packt Publishing has endeavored to provide trademark information about all of the companies and
products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot
guarantee the accuracy of this information.
11 St Paul’s Square
Birmingham
B3 1RB, UK
ISBN 978-1-83763-044-8
www.packtpub.com
To my wife, Vânia, and my two sons, Bernat and Enric. Without their ongoing love and support,
I wouldn’t have been able to write this book.
Contributors
Professionally, David is a Business and Solutions architect with over 25 years of experience in
software systems architecture. He holds a Ph.D. in Telecommunications Engineering and has a strong
educational background, including master’s degrees and extensive technological training.
Additionally, he is a scientific-technical evangelist, having authored more than thirty books.
David’s areas of expertise encompass APIs and their applications in various markets such as Banking,
Insurance, and Retail. He is well-versed in Artificial Intelligence, Digital Transformation, and the API
and Open Economy.
Christos Gkoros is a seasoned software engineer and architect with over 13 years of experience in
the industry. He has worked on a variety of projects in different technologies and industries, always
striving to find the best possible solution. With a focus on APIs, he is currently exploring ways to
help engineers in areas like API Design, API Management, and Strategy.
Christos has a proven track record of transforming complex challenges into streamlined, secure
systems, having spearheaded API design at Postman and microservice architecture at Vodafone. He is
passionate about mentorship and education and is committed to helping future talent grow and
succeed in the field.
Table of Contents
Preface
Part 1: The API Product
API-as-a-Product
Business value
Monetization models
The freemium model
Tiered model
PAYG model
Support and documentation
Security
Logging and monitoring
Rate-limiting
Authentication and authorization
Summary
Specifying an API
Technical requirements
Choosing the type of API to build
Different types of APIs
API specification formats
OpenAPI
IDL (protocol buffers)
GraphQL
WSDL
AsyncAPI
Creating a machine-readable API definition
Following API governance rules
API design
API life cycle management
Summary
Part 3: Implementing an API Product
Development Techniques
Technical requirements
Prototyping an API
Choosing a programming language and framework
Factors to consider
Popular languages for building APIs
Node.js
Python
Ruby
Java
Go
Rust
Comparing programming languages
Generating server code from a specification
Generating server code using Postman
Generating server code using OpenAPI Generator
Summary
10
API Security
What is API security?
Security testing
Authentication
API key management
Token management
Authorization
RBAC
OAuth scopes
Summary
11
API Testing
Contract testing
Performance testing
Acceptance testing
Summary
12
13
14
15
Distribution Channels
What is API distribution?
Pricing strategy
API portal
Community
Marketplaces
Documentation
Summary
Part 5: Maintaining an API Product
16
User Support
Helping users get their jobs done
Support channels
Prioritizing bugs and feature requests
Summary
17
API Versioning
Technical requirements
Managing multiple API versions
Breaking changes
Communicating changes
Summary
18
Index
Other Books You May Enjoy
Preface
Building an API Product is a comprehensive guide that ranges from the fundamentals of APIs and
their inner workings to mastering the steps involved in building successful API products. With this
book, you will be able to confidently and effectively create cutting-edge API products that excel in
today’s competitive market.
Who this book is for
This is a book that helps product managers and software developers navigate the world of APIs to
build programmable products. You don’t have to be an experienced professional to learn from this
book, as long as you have a basic knowledge of internet technologies and an understanding of how
users interact with a product.
What this book covers
Chapter 1, What Are APIs?, introduces you to API fundamentals, origins, and types such as REST,
gRPC, AMQP, and MQTT.
Chapter 2, API User Experience, explores how the API user experience is vital, second-degree
experience, and the impact of friction on success.
Chapter 3, API as a Product, outlines an API as a standalone product, emphasizing business value,
monetization options, support, documentation, and crucial security.
Chapter 4, API Life Cycle, provides an overview of the API life cycle stages, covering design,
implementation, release, and maintenance, offering an opinionated approach to API product
management.
Chapter 5, Elements of API Product Design, introduces you to the key API product design stages,
connecting ideation, strategy, definition, validation, and specification, paving the way for an in-depth
exploration.
Chapter 6, Identifying an API Strategy, analyses the strategy stage of API design, emphasizing
identifying stakeholders, determining business objectives, and understanding user personas and
behaviors.
Chapter 7, Defining and Validating an API Design, covers the techniques for defining and validating
API design, starting with strategy-derived information and exploring API mocks, UI integration, and
stakeholder iteration.
Chapter 8, Specifying an API, guides you on how to select an API architectural type based on
behaviors and capabilities, refining the definition with constraints and industry practices and creating
a machine-readable representation with governance rules.
Chapter 10, API Security, explores API security, emphasizing its importance, distinguishing between
authentication and authorization, and introducing a security testing technique called fuzzing.
Chapter 11, API Testing, introduces you to API testing methods, covering contract testing to ensure
specification compliance, performance testing execution, and the connection of acceptance testing to
user personas.
Chapter 12, API Quality Assurance, covers API quality assurance, introducing behavioral testing to
validate against identified behaviors and setting up API monitors for periodic testing.
Chapter 13, Deploying the API, provides an overview of the API deployment process, covering
continuous integration, agility, automated testing, deployment, and API gateway trade-offs.
Chapter 14, Observing API Behavior, introduces you to API usage analytics, APM, and user
feedback analysis to identify and measure important metrics, usage patterns, and behavior.
Chapter 15, Distribution Channels, covers API distribution strategies, including pricing, API portals,
marketplace listing, and documentation options to enhance user activation.
Chapter 16, User Support, delves into ways to ensure user success with an API, covering support
channels, forums, and prioritizing bug fixes and feature requests from user feedback.
Chapter 17, API Versioning, explores techniques for managing multiple API versions, handling
breaking changes effectively, and communicating changes to users using machine-readable methods.
Chapter 18, Planning API Retirement, discusses API retirement, covering its definition,
considerations, and communication to users and conducting a retrospective to document what you
have learned from the process.
We also have other code bundles from our rich catalog of books and videos available at
https://github.com/PacktPublishing/. Check them out!
Conventions used
There are a number of text conventions used throughout this book.
Code in text: Indicates code words in text, database table names, folder names, filenames, file
extensions, pathnames, dummy URLs, user input, and Twitter handles. Here is an example: “Mount
the downloaded WebStorm-10*.dmg disk image file as another disk in your system.”
When we wish to draw your attention to a particular part of a code block, the relevant lines or items
are set in bold:
[default]
exten => s,1,Dial(Zap/1|30)
exten => s,2,Voicemail(u100)
exten => s,102,Voicemail(b100)
exten => i,1,Voicemail(s0)
$ mkdir css
$ cd css
Bold: Indicates a new term, an important word, or words that you see onscreen. For instance, words
in menus or dialog boxes appear in bold. Here is an example: “Select System info from the
Administration panel.”
Get in touch
Feedback from our readers is always welcome.
General feedback: If you have questions about any aspect of this book, email us at
[email protected] and mention the book title in the subject of your message.
Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do
happen. If you have found a mistake in this book, we would be grateful if you would report this to us.
Please visit www.packtpub.com/support/errata and fill in the form.
Piracy: If you come across any illegal copies of our works in any form on the internet, we would be
grateful if you would provide us with the location address or website name. Please contact us at
[email protected] with a link to the material.
If you are interested in becoming an author: If there is a topic that you have expertise in and you
are interested in either writing or contributing to a book, please visit authors.packtpub.com.
Do you like to read on the go but are unable to carry your print books everywhere?
Is your eBook purchase not compatible with the device of your choice?
Don’t worry, now with every Packt book you get a DRM-free PDF version of that book at no cost.
Read anywhere, any place, on any device. Search, copy, and paste code from your favorite technical
books directly into your application.
The perks don’t stop there, you can get exclusive access to discounts, newsletters, and great free
content in your inbox daily
https://packt.link/free-ebook/9781837630448
3. That’s it! We’ll send your free PDF and other benefits to your email directly
Part 1:The API Product
This part provides a comprehensive guide to API development and management, beginning with
fundamental concepts, types, and origins, followed by a focus on user experience and the significance
of the API as a standalone product. It then delves into the API life cycle stages, covering design,
implementation, release, and maintenance, with an opinionated approach for effective API product
management.
Chapter 3, API-as-a-Product
The chapter begins by exploring different types of networks, such as the internet, and how APIs work
on them. You will then be guided through the history of APIs. You’ll see how APIs came to life and
understand how certain concepts in use today were born. Finally, you’ll see that there are different
technologies and tools that you can use to build an API product from scratch.
By the end of this chapter, you will know that APIs can exist on different types of networks. You will
understand what those networks are and what the most appropriate one for your API product is. You
will also know that there are synchronous and asynchronous APIs and what those terms mean. Most
importantly, you will know how to pick the right type of API and tools to build your API.
Local APIs
Local interfaces are the most used type of API, even if they’re often seen as invisible. All the
applications that run on a device need to communicate with the hardware. Applications interact with
the device via local APIs. They offer the advantage of providing a standard method of programming
the device to behave according to what users want. POSIX is one such standard created by the IEEE
Computer Society. It stands for Portable Operating System Interface, and its goal is to establish a
layer of communication that is standard across different operating systems. Another similar standard
is the Single UNIX Specification (SUS). macOS, a popular operating system developed by Apple
Inc., is considered partly compliant with POSIX and fully compliant with the SUS. This means that
anyone that interacts with macOS knows that it follows certain rules and conventions that have been
standardized. In theory, an application that is built to run on macOS could also run on other systems
that are compliant with the same standards.
By now, it’s clear that operating systems’ standards and libraries offer a way of interacting with the
lowest layers of computing devices. Another form of abstraction that encapsulates reusability at a
higher level is available through software modules. Most modern scripting programming languages
have the ability to create and use modules. Modular software development has become a popular way
of building applications. Modules provide functionality that is ready to be used and increase the
speed at which applications are built.
A widespread module system exists for the JavaScript programming language. Its name is npm, the
Node Package Manager. Its authors claim that npm is the world’s largest software registry, with
over one million modules available to be used by anyone. According to GitHub, JavaScript is the
number one used programming language at the time of writing. In fact, JavaScript has been in the
first position for the last eight years at least. Because npm is used by applications written in
JavaScript, it’s the most used module system.
Other module systems exist for different programming languages, and they all share that they want to
facilitate the reuse of functionality and increase the speed of developing software. Python, the second
most popular programming language, has PyPI, the Python Package Index. The third most popular
programming language, Java, also has its package system, Maven. There are all kinds of modules
ready for anyone to use on their applications. The point is that anyone is free to create and publish
modules and also to reuse modules that other people have published. Hence, a vast ecosystem of
modular software development keeps growing.
While local interfaces deal with the interaction between different parts of a local system, some of
those parts let you communicate with the outside world. Communication with remote systems is also
abstracted and standardized in the form of APIs. Read on to learn more about the different remote
APIs and how they can enhance the features of an application.
Remote APIs
Most people think of APIs as a way to interact with software that is running remotely. They tend to
ignore all the local interfaces that you’ve read about before—not because local APIs aren’t important,
but because they feel invisible. The opposite happens with remote APIs. Instead of being invisible,
remote APIs feel like they’re the most critical part of an application. The act of starting a connection
to a system that is running on a different part of a computer network feels like something worth
paying attention to. Remote connectivity can be split according to the type of network being used.
Let’s focus on local area networks (LANs) and wide area networks (WANs) because that’s where
most APIs operate.
LANs connect devices that are physically in the same location. The types of applications that exist on
a LAN are meant to be accessed exclusively by devices that are connected to the same network. APIs
that operate on LANs are typically focused on supporting specific classes of applications and not on
providing generic services to consumers. In other words, LAN APIs offer a way for devices to
connect to applications running on the same network. As with local APIs, here, the goal is to
standardize how the same type of applications communicate on LANs.
Databases are one type of application that is widely used in local networks. The ODBC standard was
created to standardize communication between applications and databases. ODBC stands for Open
Database Connectivity and is a standard API for accessing databases. Applications that use ODBC
can be ported across different database systems without having to be rewritten. You can, for instance,
develop a warehouse stock application that uses the MySQL database system. Suppose that, at some
point, you decide to switch to Oracle or some other database system. You don’t have to rewrite your
application as long as the database system supports ODBC. In the same way, if you decide to change
the implementation of your application to a different programming language, you don’t have to
change the database system. As long as the programming language supports ODBC, you know that
you’ll be able to interact with your database.
Printing is another popular activity on local networks. As you would expect, there are APIs that
standardize the communication between printers and other devices in the same LAN. One such API is
the Line Printer Remote protocol, or LPR. This protocol lets you interact with a printer,
programming it to print documents and even changing the configuration options of the target printer.
Even though printing happens primarily in LANs, it’s a type of application that can also be carried
out across the internet. To make communication with printers work easily outside LANs, there is a
remote API called Internet Printing Protocol, or IPP. According to Michael Sweet from Apple Inc.,
“at least 98% of all printers sold since 2010 support IPP." It became so popular because it offers
features such as authentication, access control, and encryption of data transmitted to the printer. And
it’s not the only API that operates on the internet, as you’ll see if you keep reading.
When you hear the term API, you immediately think about services that run on the internet. That’s
because wide access to networked services helped popularize the creation of APIs. Externalizing
features of an application feels natural in an environment where all services are connected to the
same network. Many times, you can even confuse internet APIs with the services that they expose.
We often talk about the API as the offering rather than the interface. That indicates that the internet
has contributed to the fragmentation of the types of APIs that are available. There are API types that
are best suited for reading data while other types are better used for synchronously storing
information, and there are types that work well to asynchronously share information about events.
Let’s start by exploring API types that let you easily read data from a remote server on the internet.
You can say that the simplest way to read data remotely is to directly access a document. However,
you would only call that an API if there were some degree of programmability involved. In other
words, when you’re directly retrieving a document, you’re not sending any parameters to an API. To
make it programmable, there has to be something on the server that interprets the request parameters
and changes the returned output based on what is being requested. A remote procedure call, or
RPC, is an example of a type of API that lets the requester send parameters to a server and, in return,
receive information. In the same way that you can read information with it, you can also use it to
store information on a server. In that case, you’re sending parameters along with the information that
you want to store. Depending on the size of the data—what you call an API payload—you can
choose what type of API and which technology to use.
As a rule of thumb, anything that happens on the internet works better with short-lived connections.
The internet is an open network. Connections between different points on the internet can change
without notice, and that can affect the quality of communication. Communicating asynchronously is
also an option. There are types of APIs that focus specifically on letting you share information in an
asynchronous way. Usually, these are used for sharing information about events, but also for
receiving the result of long-running operations. You make a request that you know is going to take a
long time to finish. When the request is completed by the server, it will share the result with you. If
availability is what matters the most, then you decide the type of API based on what is reliable most
of the time. Many APIs end up running on top of the web because it’s the most widely used protocol,
and you accept it as having a high resilience. In fact, web APIs are what you’ll be working on most of
the time when you’re building API products.
Web APIs are a type of API that uses the internet and web-specific protocols to communicate. In the
same way that the remote APIs that you’ve read about before make remote resources appear as local,
web APIs offer the same functionality for resources available on the web. On the web, it’s a common
approach to identify the supported media types that can be transferred from the server to the client.
That is also the case for web APIs. Two of the most used media types are the Extensible Markup
Language, or XML, and the JavaScript Object Notation, or JSON. These media types can be
easily used and interpreted by API client software. The big advantage of web APIs over other types of
remote APIs is the features that the web offers. Just by using the web, you have access to content
caching, or the ability to temporarily store responses that can be reused between requests. You also
have access to authentication mechanisms that don’t require any specific implementation. Finally,
you become part of a vast ecosystem of server and client tools that are widely available for anyone to
use.
While there are different types of APIs, you’re reading this book most probably because you’re
interested in web APIs. As you’ve seen before, to most people, APIs are a synonym for something
such as a programmable interface running on the web. The API that you’ll build will probably run on
the web as well, so let’s use that as a guide throughout the rest of the book. Keeping in mind that
there are several types of APIs, let’s focus on how to build web APIs. To get there, let’s look now at
how APIs came to exist and how they have been evolving.
To understand how APIs were invented, let’s go back in time to circa 1950. At that time, computing
was just getting started, and the first known mention of a software module was made by Herman
Goldstine and John von Neumann. The authors were referring to local APIs in the form of modules
or, as they called it, “subroutines.” In their Report on the Mathematical and Logical Aspects of an
Electronic Computing Instrument from 1947, they explain what a subroutine is. To the authors, a
subroutine is a special kind of routine—a set of program instructions that can be reused. They
describe that a subroutine has the purpose of being substituted inside any existing routine. It’s clear
that the authors were focusing on reusability, as you’ve read before in this chapter. In fact, from then
on, APIs have been used as a way to reduce the amount of programming required to build an
application.
However, the work of Goldstine and von Neumann was purely theoretical and couldn’t be put into
practice at that time. It was only when the Electronic Delay Storage Automatic Calculator, or
EDSAC, was created that software modules were actually used. In 1951, Maurice Wilkes, the creator
of EDSAC, was inspired by the work of Goldstine and von Neumann. Wilkes introduced the use of
modules as a way to reuse functionality and make it easier to write programs from scratch. Wilkes,
jointly with Wheeler and Gill, describes how subroutines could be used in their book The
Preparation of Programs for an Electronic Digital Computer. In this, they explain that with a library
of subroutines, it should be simple to program sophisticated calculations. You’d only have to write a
master routine that, in turn, calls the various subroutines where the different calculations are
executed.
Still, the first time the term “application program interface” (notice that the word used isn’t
“programming”) appeared was probably in the Data Structures and Techniques for Remote Computer
Graphics paper published in 1968. In this, its authors, Ira Walter Cotton and Frank S. Greatorex,
notice the importance of the reusability of code in the context of hardware replacement. The paper
mentions that even if you change the hardware, a “consistent application program interface could be
maintained.”
Another random document with
no related content on Scribd:
onneton, sillä hereillä tekee arvosteluni minut tyytymättömäksi, aina
kuiskaten minulle, että olen poissa ystäväni luota. Mutta lempeät
uneni öisin hyvittävät minua ja saavat minut uskomaan, että olen
hänen sylissään. Kiitän Jumalaa onnellisista unistani, samoin kuin
hyvästä levostanikin, sillä ne tarjoovat tyydytystä kohtuullisille
toiveille ja sellaisille ihmisille, jotka tyytyvät vähäänkin
onnellisuuteen. Eikä liene synkkämielinen se käsitys, että me kaikki
olemme kuin nukuksissa tässä maailmassa, että tämän elämän
käsitykset ovat pelkkiä unelmia verrattuina tulevaisen maailman
tajuntaan, niinkuin unihaaveet selvän päivän tajunnan rinnalla.
Molemmat ovat yhtä erehdyttäviä, ja toinen näyttää vain olevan
toisen vertauskuva. Me olemme vähän enemmän kuin oma itsemme
nukkuessamme, ja ruumiimme uinailu tuntuu aloittavan sielun
valveutumisen. Aistimemme ovat kyllä sidotut, mutta järkemme
vapautuu, eivätkä ajatuksemme valveilla ollessamme voi kilpailla
unessa saamiemme haaveiden kanssa.
Updated editions will replace the previous one—the old editions will
be renamed.
1.D. The copyright laws of the place where you are located also
govern what you can do with this work. Copyright laws in most
countries are in a constant state of change. If you are outside the
United States, check the laws of your country in addition to the terms
of this agreement before downloading, copying, displaying,
performing, distributing or creating derivative works based on this
work or any other Project Gutenberg™ work. The Foundation makes
no representations concerning the copyright status of any work in
any country other than the United States.
• You pay a royalty fee of 20% of the gross profits you derive from
the use of Project Gutenberg™ works calculated using the
method you already use to calculate your applicable taxes. The
fee is owed to the owner of the Project Gutenberg™ trademark,
but he has agreed to donate royalties under this paragraph to
the Project Gutenberg Literary Archive Foundation. Royalty
payments must be paid within 60 days following each date on
which you prepare (or are legally required to prepare) your
periodic tax returns. Royalty payments should be clearly marked
as such and sent to the Project Gutenberg Literary Archive
Foundation at the address specified in Section 4, “Information
about donations to the Project Gutenberg Literary Archive
Foundation.”
• You comply with all other terms of this agreement for free
distribution of Project Gutenberg™ works.
1.F.
1.F.4. Except for the limited right of replacement or refund set forth in
paragraph 1.F.3, this work is provided to you ‘AS-IS’, WITH NO
OTHER WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PURPOSE.
Please check the Project Gutenberg web pages for current donation
methods and addresses. Donations are accepted in a number of
other ways including checks, online payments and credit card
donations. To donate, please visit: www.gutenberg.org/donate.
Most people start at our website which has the main PG search
facility: www.gutenberg.org.