RESTful API设计与实践：连接异构系统

需积分: 10 121 浏览量更新于2024-07-20 收藏 3.07MB PDF 举报

"RESTful Web Services 英文版" RESTful Web Services是一种设计网络应用程序和接口的架构风格，它遵循Representational State Transfer（表述性状态转移）原则，是Web服务领域中的一个重要概念。随着互联网的发展，RESTful风格的Web服务越来越流行，尤其是在构建可互操作的异构系统之间进行数据交换时。例如，Twitter、Google和Redmine等知名平台的API都是基于RESTful设计的。 REST的基本原则包括以下几点： 1. **无状态**：每个请求都包含处理该请求所需的所有信息，服务器不保存任何会话状态。这使得服务器能够更高效地处理请求，同时降低了系统的复杂性。 2. **缓存**：允许客户端缓存响应结果，提高性能，减少不必要的服务器负载。 3. **统一接口**：RESTful服务通过四个主要接口来与资源交互：GET用于获取资源，POST用于创建新资源，PUT用于更新已有资源，DELETE用于删除资源。此外，还有HEAD、OPTIONS和其他辅助方法。 4. **层次系统**：客户端可以透明地与中间层交互，而无需了解这些中间层的存在。这有助于系统扩展和管理。 5. **使用URI（统一资源标识符）**：每个资源都有一个唯一的URI，客户端通过URI来定位和操作资源。 6. **资源的表示**：资源通过各种媒体类型（如JSON、XML）来表示，使得数据能在不同的平台和语言之间共享。 RESTful服务的设计通常遵循以下步骤： 1. **定义资源**：确定服务提供的核心实体，并为每个实体分配一个URI。 2. **选择合适的HTTP方法**：根据操作类型（CRUD：创建、读取、更新、删除）选择合适的HTTP动词。 3. **设计资源的表示形式**：决定如何将资源数据编码为JSON或XML等格式。 4. **处理错误**：通过HTTP状态码返回错误信息，比如404表示资源未找到，403表示禁止访问等。 5. **考虑安全性**：使用HTTPS协议确保数据传输的安全性，还可以通过OAuth等授权机制保护资源。在开发RESTful服务时，开发者通常会使用一些框架和库来简化实现，例如在Java中有Spring Boot和Jersey，在Ruby on Rails中则有内置的REST支持。同时，书籍如《Web Services on Rails》可以帮助开发者深入理解如何在Rails环境下构建RESTful服务。 O'Reilly出版社出版了一系列与Web服务相关的书籍，如《Ajax on Rails》、《Ruby on Rails: Up and Running》等，为开发者提供了丰富的学习资源。此外，O'Reilly的Safari Bookshelf在线参考图书馆提供了超过1000本书籍的搜索和订阅服务，便于程序员和IT专业人士快速查找答案，解决实际工作中的问题。 O'Reilly还组织各类技术会议，聚焦于新兴技术和平台，为创新者提供交流平台，推动技术进步。访问conferences.oreilly.com可查看即将举行的相关活动。

Reuniting the Webs

Programmers have been using web sites as web services for years—unofficially, of

course.

It’s difficult for a computer to understand web pages designed for human

consumption, but that’s never stopped hackers from fetching pages with automated

clients and screen-scraping the interesting bits. Over time, this drive was sublimated

into programmer-friendly technologies for exposing a web site’s functionality in offi-

cially sanctioned ways—RSS, XML-RPC, and SOAP. These technologies formed a

programmable web, one that extended the human web for the convenience of software

programs.

Our ultimate goal in this book is to reunite the programmable web with the human

web. We envision a single interconnected network: a World Wide Web that runs on

one set of servers, uses one set of protocols, and obeys one set of design principles. A

network that you can use whether you’re serving data to human beings or computer

programs.

The Internet and the Web did not have to exist. They come to us courtesy of misallo-

cated defense money, skunkworks engineering projects, worse-is-better engineering

practices, big science, naive liberal idealism, cranky libertarian politics, techno-

fetishism, and the sweat and capital of programmers and investors who thought they’d

found an easy way to strike it rich.

The result is, amazingly, a simple, open (for now), almost universal platform for net-

worked applications. This platform contains much of human knowledge and supports

most fields of human endeavor. We think it’s time to seriously start applying its rules

to distributed programming, to open up that information and those processes to au-

tomatic clients. If you agree, this book will show you to do it.

What’s in This Book?

In this book we focus on practical issues: how to design and implement RESTful web

services, and clients for those services. Our secondary focus is on theory: what it means

to be RESTful, and why web services should be more RESTful instead of less. We don’t

cover everything, but we try to hit today’s big topics, and because this is the first book

of its kind, we return to the core issue—how to design a RESTful service—over and

over again.

The first three chapters introduce web services from the client’s perspective and show

what’s special about RESTful services.

For an early example, see Jon Udell’s 1996 Byte article “On-Line Componentware” (http://www.byte.com/

art/9611/sec9/art1.htm). Note: “A powerful capability for ad hoc distributed computing arises naturally from

the architecture of the Web.” That’s from 1996, folks.

xviii | Preface

Chapter 1, The Programmable Web and Its Inhabitants
In this chapter we introduce web services in general: programs that go over the
Web and ask a foreign server to provide data or run an algorithm. We demonstrate
the three common web service architectures: RESTful, RPC-style, and REST-RPC
hybrid. It shows sample HTTP requests and responses for each architecture, along
with typical client code.
Chapter 2, Writing Web Service Clients
In this chapter we show you how to write clients for existing web services, using
an HTTP library and an XML parser. We introduce a popular REST-RPC service
(the web service for the social bookmarking site del.icio.us) and demonstrate cli-
ents written in Ruby, Python, Java, C#, and PHP. We also give technology
recommendations for several other languages, without actually showing code.
JavaScript and Ajax are covered separately in Chapter 11.
Chapter 3, What Makes RESTful Services Different?
We take the lessons of Chapter 2 and apply them to a purely RESTful service:
Amazon’s Simple Storage Service (S3). While building an S3 client we illustrate
some important principles of REST: resources, representations, and the uniform
interface.
The next six chapters form the core of the book. They focus on designing and imple-
menting your own RESTful services.
Chapter 4, The Resource-Oriented Architecture
A formal introduction to REST, not in its abstract form but in the context of a
specific architecture for web services. Our architecture is based on four important
REST concepts: resources, their names, their representations, and the links be-
tween them. Its services should be judged by four RESTful properties: addressa-
bility, statelessness, connectedness, and the uniform interface.
Chapter 5, Designing Read-Only Resource-Oriented Services
We present a procedure for turning an idea or a set of requirements into a set of
RESTful resources. These resources are read-only: clients can get data from your
service but they can’t send any data of their own. We illustrate the procedure by
designing a web service for serving navigable maps, inspired by the Google Maps
web application.
Chapter 6, Designing Read/Write Resource-Oriented Services
We extend the procedure from the previous chapter so that clients can create,
modify, and delete resources. We demonstrate by adding two new kinds of re-
source to the map service: user accounts and user-defined places.
Chapter 7, A Service Implementation
We remodel an RPC-style service (the del.icio.us REST-RPC hybrid we wrote cli-
ents for back in Chapter 2) as a purely RESTful service. Then we implement that
service as a Ruby on Rails application. Fun for the whole family!
Preface | xix

Chapter 8, REST and ROA Best Practices
In this chapter we collect our earlier suggestions for service design into one place,
and add new suggestions. We show how standard features of HTTP can help you
with common problems and optimizations. We also give resource-oriented designs
for tough features like transactions, which you may have thought were impossible
to do in RESTful web services.
Chapter 9, The Building Blocks of Services
Here we describe extra technologies that work on top of REST’s big three of HTTP,
URI, and XML. Some of these technologies are file formats for conveying state, like
XHTML and its microformats. Some are hypermedia formats for showing clients
the levers of state, like WADL. Some are sets of rules for building RESTful web
services, like the Atom Publishing Protocol.
The last three chapters cover specialized topics, each of which could make for a book
in its own right:
Chapter 10, The Resource-Oriented Architecture Versus Big Web Services
We compare our architecture, and REST in general, to another leading brand. We
think that RESTful web services are simpler, more scalable, easier to use, better
attuned to the philosophy of the Web, and better able to handle a wide variety of
clients than are services based on SOAP, WSDL, and the WS-* stack.
Chapter 11, Ajax Applications as REST Clients
Here we explain the Ajax architecture for web applications in terms of web services:
an Ajax application is just a web service client that runs inside your web browser.
That makes this chapter an extension of Chapter 2. We show how to write clients
for RESTful web services using 
XMLHttpRequest and the standard JavaScript library.
Chapter 12, Frameworks for RESTful Services
In the final chapter we cover three popular frameworks that make it easy to im-
plement RESTful web services: Ruby on Rails, Restlet (for Java), and Django (for
Python).
We also have three appendixes we hope you find useful:
Appendix A, Some Resources for REST and Some RESTful Resources
The first part lists interesting standards, tutorials, and communities related to
RESTful web services. The second part lists some existing, public RESTful web
services that you can use and learn from.
Appendix B, The HTTP Response Code Top 42
Describes every standard HTTP response code (plus one extension), and explains
when you’d use each one in a RESTful web service.
Appendix C, The HTTP Header Top Infinity
Does the same thing for HTTP headers. It covers every standard HTTP header,
and a few extension headers that are useful for web services.
xx | Preface

Which Parts Should You Read?
We organized this book for the reader who’s interested in web services in general:
someone who learns by doing, but who doesn’t have much experience with web serv-
ices. If that describes you, the simplest path through this book is the best. You can start
at the beginning, read through Chapter 9, and then read onward as you’re interested.
If you have more experience, you might take a different path through the book. If you’re
only concerned with writing clients for existing services, you’ll probably focus on
Chapters 1, 2, 3, and 11—the sections on service design won’t do you much good. If
you want to create your own web service, or you’re trying to figure out what REST
really means, you might start reading from Chapter 3. If you want to compare REST
to the WS-* technologies, you might start by reading Chapters 1, 3, 4, and 10.
Administrative Notes
This book has two authors (Leonard and Sam), but for the rest of the book we’ll be
merging our identities into a single authorial “I.” In the final chapter (Chapter 12), the
authorial “I” gets a little bit more crowded, as Django and Restlet developers join in to
show how their frameworks let you build RESTful services.
We assume that you’re a competent programmer, but not that you have any experience
with web programming in particular. What we say in this book is not tied to any pro-
gramming language, and we include sample code for RESTful clients and services in a
variety of languages. But whenever we’re not demonstrating a specific framework or
language, we use Ruby (http://www.ruby-lang.org/) as our implementation language.
We chose Ruby because it’s concise and easy to read, even for programmers who don’t
know the language. (And because it’s nice and confusing in conjunction with Sam’s
last name.) Ruby’s standard web framework, Ruby on Rails, is also one of the leading
implementation platforms for RESTful web services. If you don’t know Ruby, don’t
worry: we include lots of comments explaining Ruby-specific idioms.
The sample programs in this book are available for download from this book’s official
web site (http://www.oreilly.com/catalog/9780596529260). This includes the entire
Rails application from Chapter 7, and the corresponding Restlet and Django applica-
tions from Chapter 12. It also includes Java implementations of many of the clients
that only show up in the book as Ruby implementations. These client programs use
the Restlet library, and were written by Restlet developers Jerome Louvel and Dave
Pawson. If you’re more familiar with Java than with Ruby, these implementations may
help you grasp the concepts behind the code. Most notably, there’s a full Java imple-
mentation of the Amazon S3 client from Chapter 3 in there.
Preface | xxi