程序员必读：《API设计策略指南》全解析

需积分: 14 136 浏览量更新于2024-07-24 收藏 6.12MB PDF 举报

《API设计指南》是一本由Daniel Jacobson、Greg Brail和Dan Woods合著的专业书籍，旨在为程序员提供全面的API策略设计指南。本书是英文版，于2012年出版，由Evolved Media享有版权，适用于教育、商业或销售推广目的。在美国印制，由O'Reilly Media公司发行，位于加利福尼亚州塞巴斯托波尔。作为一本详细的指导手册，它涵盖了API设计的各个方面，包括但不限于API的概念理解、架构选择、安全性考虑、性能优化、版本控制以及如何创建易于使用和可维护的接口。作者们强调了在设计API时应遵循的最佳实践，比如清晰的命名约定、文档编写的重要性、错误处理的合理性以及API版本迭代的策略。书中可能会深入探讨RESTful API设计原则，以及如何利用RESTful架构来构建可扩展、易于理解和使用的API。此外，它还会讨论API的生命周期管理，包括如何在发布前进行测试和验证，以及如何通过API Gateway或API网关服务来管理和控制API的访问。《API设计指南》也关注到了现代API经济中的关键因素，如API市场、API速率限制策略、API定价模型以及API安全措施，例如OAuth和JWT等身份验证方法。书中还可能提到API的监控、日志记录和故障排查技巧，帮助开发者确保API的稳定性和可靠性。作为Nutshell Handbook系列的一部分，这本书采用了简洁明快的写作风格，适合快速学习和查阅。同时，它还提供了在线版本供读者随时随地获取信息。如果你正在寻求一个系统化的API设计参考，或者想要提升自己的API开发技能，这本《API设计指南》无疑是一个不可或缺的资源。

Who Is This Book For?

There are a range of books on the technical aspects of APIs, including books about

REST, OAuth, XML, JSON, and others. This book is not intended to compete with

those books. In fact, although it is virtually impossible to address APIs without delving

into technical approaches, this book is not targeted at the technologists who build or

directly consume APIs. Rather, this book is designed for the people who need to make

the strategic decisions about whether an API is a good idea for their company.

Target audiences for this book include C-level executives, members of the business

development teams, product managers, and technical evangelists. Of course, there will

be plenty in this book for technologists as well, but at a higher level.

What Is an API?

API stands for application programming interface. An API can provide a hook for col-

leagues, partners, or third-party developers to access data and services to build appli-

cations such as iPhone apps quickly. The Twitter and Facebook APIs are famous ex-

amples. There are APIs that are open to any developer, APIs that are open only to

partners, and APIs that are used internally to help run the business better and facilitate

collaboration between teams.

An API, then, is essentially a contract. Once such a contract is in place, developers are

enticed to use the API because they know they can rely on it. The contract increases

confidence, which increases use. The contract also makes the connection between pro-

vider and consumer much more efficient since the interfaces are documented, consis-

tent, and predictable.

How Is an API Different from a Website?

An API is quite different from a website. A website provides information on demand.

A company puts content out in the world, and people consume it. Websites have no

contracts or structures around the use of content. If content on the website changes,

visitors who come next get the new content. Their browsers are not affected, and any

change is transparent to the user. If you dramatically redesign the website, the only

impact is on the user accustomed to seeing the content laid out in a particular way.

Humans are great at visual pattern matching; we can quickly adjust to a new design

and find what we need. That doesn’t mean that users don’t complain when their favorite

site is redesigned, but they almost always adapt.

An API is quite different because it has a contract, and programs are built on top of

that contract. Programs, unlike humans, are not flexible and almost always terrible at

pattern matching. If you alter anything in the contract of the API, the ripple effect on

the apps built on top of it is potentially quite large.

4 | Chapter 1: The API Opportunity

Our Working Definition of an API

Technical definition: An API is a way for two computer applications to talk to each

other over a network (predominantly the Internet) using a common language that they

both understand.

APIs follow a specification, meaning:

• The API provider describes exactly what functionality the API will offer

• The API provider describes when the functionality will be available and when it

might change in an incompatible way

• The API provider may outline additional technical constraints within the API, such

as rate limits that control how many times a particular application or end user is

allowed to use the API in a given hour, day, or month

• The API provider may outline additional legal or business constraints when using

the API, such as branding limitations, types of use, and so on

• Developers agree to use the API as described, to use only the APIs that are de-

scribed, and to follow the rules set out by the API provider

In addition, the API provider may offer other tools, such as:

• Mechanisms to access the API and understand its terms of use

• Documentation to aid in understanding the API

• Resources such as example programs and developer communities to support those

using the API

• Operational information about the health of the API and how much use it is getting

Remember that the structure of the API is part of the contract. The

contract is binding, and it cannot be changed casually.

You should treat an API like a software product, taking into account versioning, back-

ward compatibility, and ramp-up time to accommodate any new functionality. There

should be a balance between supporting your existing base while at the same time

keeping up with necessary changes so that your API grows with your business and

follows its planned evolution.

This does not mean that the API can never change. On the contrary, an API is an online

product that can change almost constantly to meet the needs of the business, or to serve

the current traffic load in the most efficient way. But these are changes to the imple-

mentation, not to the interface. When done right, the implementation of an API can

change on a daily basis, or even more often, while the interface remains consistent.

What Is an API? | 5

…But APIs and Websites Have a Lot in Common

APIs, like websites, are expected to be available 24/7, 365 days a year. Developers, like

website users, do not have much patience for “scheduled downtime” every Saturday

morning. All of this can create a challenge for building an API on an existing enterprise

technology infrastructure, using systems that may have been designed with an “end of

day” cycle, after which they are shut down until the next day (such as banking systems).

Successful websites can, and are, updated continuously to change the design and tweak

features. This is possible because websites are live entities out on the network that can

be easily changed without changing the clients—there is no need to push a software

update to the users.

APIs are not much different in this respect. Assuming your API remains backward

compatible, an API program can introduce new features and change the implementa-

tion of existing features without “breaking” the clients. As long as you uphold the

contract between your API and the developers who use it, the API can change on a

“web schedule” rather than on an “enterprise IT schedule.” The result is a better, more

responsive API program.

In fact, changes to both APIs and websites can be driven by analytics on behavior of

the applications and end users. In both cases, a good design and product management

team constantly checks the analytics to see what parts of the site or API are succeeding

and which are failing. The result should feed into regular development sprints, which

over time build a much more robust API or website.

Who Uses an API?

We call the company or organization that offers an API the API provider. This book is

largely aimed at API providers (or those who are thinking about offering an API).

We decided to call the people who use your API to create applications developers. It’s

true that many types of people may be interested in your API, including business own-

ers, marketing gurus, executives, and others, but the people who will eventually create

the applications are developers. Developers are the primary audience for your API.

We decided to call the people who use the applications that developers create end

users. They are the secondary audience for your API and often the audience driving

many of your API decisions. Depending on the content made available via your API,

you may have particular concerns to address, such as copyright, legal use, and so on,

that relate to this secondary audience.

6 | Chapter 1: The API Opportunity

Types of APIs

We see two types of APIs: private and public. No matter what you may hear in the

media, private APIs are the more prevalent variety. You know about the Facebooks and

Twitters of the world and their use of APIs. What you probably don’t know is that

those same companies are likely making much more extensive use of their own APIs

to drive their websites, mobile apps, and other customer-facing products. In our ex-

perience, visible public APIs like these are just the tip of the iceberg. Like the large

underwater mass of an iceberg, most APIs are private and imperceptible, internal to

companies, used by staff and by partners with contractual agreements. This use of APIs

is what is really driving the API revolution. Do not limit your thinking about the ways

APIs can be used to public examples like the App Store. Partner and internal use of

APIs is often more valuable.

Much of the discussion of APIs assumes that they must be open to the public to be of

value. This is not the case. We believe that private APIs are having a transformational

impact on most companies, in many cases much more so than public APIs.

The New York Times API started as a private API and is transforming their business.

“The NYT API grew out of a need to make our own internal content management

system more accessible so that we could get the most from our content,” said Derek

Willis, Newsroom Developer at the Times. “The API offered a way to give more people

access to create more interesting pieces. We are the biggest users of our own API, and

that’s not by accident. The API helps our business in other ways: creating brand aware-

ness and helping us attract talent. But fundamentally, it helps us do our own jobs

better.”

To further frame this discussion, let’s clarify what we mean by public and private. Public

means that the API is available to almost anyone with little or no contractual arrange-

ment (beyond agreement to the terms of use) with the API provider. Private APIs are

used in a variety of ways, whether to support internal API efforts or a partner’s use of

the API. API providers also offer private APIs to large customers with appropriate legal

contracts. Private and public really refers to the formality of the business arrangement.

It doesn’t refer to the API content nor does it refer to the applications developed using

the API.

Finally, public and private APIs are, in the end, still APIs. Often a company will start

with a private API and eventually open some or all of it for public access, possibly with

additional restrictions. Other times, a company will launch a public API, then realize

how important it is for internal development and in the end it is private use, not public

use, that provides the real business benefit.

AccuWeather, for example, is well known for providing weather data to the general

public, which would lead most to believe that their APIs are public. But remember: the

private/public distinction refers to the arrangement with partners, not to the availability

Types of APIs | 7

of content to end-users. AccuWeather’s API, like other private APIs, can be and is used

to offer applications to the general public.

AccuWeather’s API is highly customized for partners; it’s a key differentiator. “We

have over 300 variations of our API. This is a result of our company philosophy—

custom for the customer, or for each company using the API,” said Chris Patti, director

of technology at AccuWeather. “We respond on a dime to customer requests, and it’s

a competitive advantage for us. We’ve won contracts by being able to respond to cus-

tom requests, like serving data vs. GPS coordinates. This is why customers work with

us, because of our creativity and responsiveness.”

API providers often choose to offer different views of business assets internally and

externally. Derek Willis said, “We might offer more than one version of an API to

support multiple use cases or business models. We might have different API endpoints

for different audiences. For example, the public article search may offer only truncated

articles while the internal article search API might offer the full text.”

Why Now?

APIs have reached their breakout moment for three reasons:

Process maturity

APIs are not just about technology. As in many business problems, what we really

have is a people problem. APIs offer a common pattern to help people to collabo-

rate.

Self-service

Why did open source succeed? Although the availability of source code is often the

focus of discussions about the success of open source, the idea of self-service is

much more important. Only a tiny percentage of developers wanted to read or

modify source code. Instead, open source software displaced commercial software

because developers did not have to ask anyone for permission to take the software

and run with it. Publishers of APIs learned from open source. A successful API

must be available on a self-service basis and be easy to use. Like open source

projects, the best APIs have thriving online communities, either internal to the

company or in the larger public developer community (or both). In the most suc-

cessful developer communities, the most active members don’t work for the com-

pany that provides the API—rather, they help because the API is critical to what

they do and they love helping others see its value.

Technological maturity

Even though technologists have used APIs for decades, few people realize that the

explosion of activity going on with Twitter, Netflix, and others online is based on

APIs. The end result that people see is a lot of traffic, but it’s not web traffic. It’s

API traffic. Companies like Google, Amazon, Twitter, Sears, Alcatel-Lucent, and

thousands of others are using APIs to change their businesses.

8 | Chapter 1: The API Opportunity

剩余147页未读，继续阅读

茶果果

粉丝: 0
资源: 9

程序员必读：《API设计策略指南》全解析

Python技术API设计指南.docx

http-api-design-ZH_CN, HTTP API 设计指南(http-api-design-ZH_CN)，翻译自https.zip

HTTP API 设计指南

REST-API-设计指南：NBB的REST-ish API设计指南

C++ API 设计指南

C++ API设计指南

RESTful API设计指南

C++ API设计指南(2011)

RESTful API设计指南与实践

一款高效的Vue 3低代码表单，可视化设计，一键生成源码

最新资源