책/RESTfulWebServices

Leonard Richardson, Sam Ruby

2008년 저작이라서 좀 오래됐음.

Chapter 1. The Programmable Web and Its Inhabitants

Kinds of Things on the Programmable Web

The programmable web is based on HTTP and XML. Some parts of it serve HTML, JavaScript Object Notation (JSON), plain text, or binary documents, but most parts use XML. And it’s all based on HTTP: if you don’t use HTTP, you’re not on the web.

Imagine the programmable web as an ecosystem, like the ocean, containing many kinds of strange creatures. Ancient scientists and sailors classified sea creatures by their superficial appearance: whales were lumped in with the fish. Modern scientists classify animals according to their position in the evolutionary tree of all life: whales are now grouped with the other mammals. There are two analogous ways of classifying the services that inhabit the programmable web: by the technologies they use (URIs, SOAP, XML-RPC, and so on), or by the underlying architectures and design philosophies.

When it comes to classifying the programmable web, most of today’s terminology sorts services by their superficial appearances: the technologies they use. These classifications work in most cases, but they’re conceptually lacking and they lead to whale-fish mistakes. I’m going to present a taxonomy based on architecture, which shows how technology choices follow from underlying design principles. I’m exposing divisions I’ll come back to throughout the book, but my main purpose is to zoom in on the parts of the programmable web that can reasonably be associated with the term “REST.”

HTTP: Documents in Envelopes

Method Information

Scoping Information

The Competing Architectures

Now that I’ve identified the two main questions that web services answer differently, I can group web services by their answers to the questions. In my studies I’ve identified three common web service architectures: RESTful resource-oriented, RPC-style, and REST-RPC hybrid. I’ll cover each in turn.

RESTful, Resource-Oriented Architectures

A few well-known examples of RESTful, resource-oriented web services include:

• Services that expose the Atom Publishing Protocol and its variants such as GData
• Amazon’s Simple Storage Service (S3)
• Most of Yahoo!’s web services
• Most other read-only web services that don’t use SOAP
• Static web sites
• Many web applications, especially read-only ones like search engines

Whenever I cover unRESTful architectures, as well as architectures that aren’t resource-oriented, I do it with some ulterior motive. In this chapter, I want to put RESTful web services into perspective, against the larger backdrop of the programmable web. In Chapter 2, I’m widening the book’s coverage of real web services, and showing that you can use the same client tools whether or not a service exactly fits my preferred architecture. In Chapter 10, I’m making an argument in a long-running debate about what the programmable web should look like.

RPC-Style Architectures

A few well-known examples of RPC-style web services:

• All services that use XML-RPC
• Just about every SOAP service (see the Technologies on the Programmable Web” section later in this chapter for a defense of this controversial statement)
• A few web applications (generally poorly designed ones)

REST-RPC Hybrid Architectures

This is a term I made up for describing web services that fit somewhere in between the RESTful web services and the purely RPC-style services. These services are often created by programmers who know a lot about real-world web applications, but not much about the theory of REST.

The Human Web Is on the Programmable Web

In the previous sections I claimed that all static web sites are RESTful. I claimed that web applications fall into one of the three categories, the majority being REST-RPC hybrids. Since the human web is made entirely of static web sites and web applications, this means that the entire human web is also on the programmable web! By now this should not be surprising to you. A web browser is a software program that makes HTTP requests and processes the responses somehow (by showing them to a human). That’s exactly what a web service client is. If it’s on the Web, it’s a web service.

My goal in this book is not to make the programmable web bigger. That’s almost impossible: the programmable web already encompasses nearly everything with an HTTP interface. My goal is to help make the programmable web better: more uniform, better-structured, and using the features of HTTP to greatest advantage.

Technologies on the Programmable Web

I’ve classified web services by their underlying architectures, distinguishing the fish from the whales. Now I can examine the technologies they use, without confusing technology and architecture.

HTTP

URI

XML-RPC

SOAP

WS-*

WSDL

WADL

Leftover Terminology

Believe it not, there are some common terms used in discussions of REST that I haven’t mentioned yet. I haven’t mentioned them because I think they’re inaccurate or entirely outside the scope of this book. But I owe you explanations of why I think this, so you can decide whether or not you agree. Feel free to skip this section if you haven’t heard these terms.

Chapter 2. Writing Web Service Clients

Web Services Are Web Sites

del.icio.us: The Sample Application

Making the Request: HTTP Libraries

Processing the Response: XML Parsers

JSON Parsers: Handling Serialized Data

Clients Made Easy with WADL

Chapter 3. What Makes RESTful Services Different?

Introducing the Simple Storage Service

Object-Oriented Design of S3

Resources

HTTP Response Codes

An S3 Client

Request Signing and Access Control

Using the S3 Client Library

Clients Made Transparent with ActiveResource

Parting Words

Chapter 4. The Resource-Oriented Architecture

I’ve shown you the power of REST, but I haven’t shown you in any systematic way how that power is structured or how to expose it. In this chapter I outline a concrete RESTful architecture: the Resource-Oriented Architecture (ROA). The ROA is a way of turning a problem into a RESTful web service: an arrangement of URIs, HTTP, and XML that works like the rest of the Web, and that programmers will enjoy using.

In Chapter 1 I classified RESTful web services by their answers to two questions. These answers correspond to two of the four defining features of REST:

• The scoping information (“why should the server send this data instead of that data?”) is kept in the URI. This is the principle of addressability.
• The method information (“why should the server send this data instead of deleting it?”) is kept in the HTTP method. There are only a few HTTP methods, and everyone knows ahead of time what they do. This is the principle of the uniform interface.

Resource-Oriented What Now?

Why come up with a new term, Resource-Oriented Architecture? Why not just say REST? Well, I do say REST, on the cover of this book, and I hold that everything in the Resource-Oriented Architecture is also RESTful. But REST is not an architecture: it’s a set of design criteria. You can say that one architecture meets those criteria better than another, but there is no one “REST architecture.”

What’s a Resource?

URIs

Addressability

Statelessness

Representations

Links and Connectedness

The Uniform Interface

That’s It!

That’s the Resource-Oriented Architecture. It’s just four concepts:

1. Resources
2. Their names (URIs)
3. Their representations
4. The links between them

and four properties:

1. Addressability
2. Statelessness
3. Connectedness
4. A uniform interface

Chapter 5. Designing Read-Only Resource-Oriented Services

Chapter 6. Designing Read/Write Resource-Oriented Services

Chapter 7. A Service Implementation

Chapter 8. REST and ROA Best Practices

Chapter 9. The Building Blocks of Services

Chapter 10. The Resource-Oriented Architecture Versus Big Web Services

Conclusion

Both REST and web services have become buzzwords. They are chic and fashionable. These terms are artfully woven into PowerPoint presentations by people who have no real understanding of the subject. This chapter, and indeed this book, is an attempt to dispel some of the confusion.

In this chapter you’ve seen firsthand the value that SOAP brings (not so much), and the complexity that WSDL brings (way too much). You’ve also seen resource-oriented alternatives listed every step of the way. Hopefully this will help you make better choices. If you can see you’ll need some of the features described in this chapter which are only available as stickers on SOAP envelopes, getting started on the SOAP path from the beginning will provide a basis for you to build on.

The alternative is to start lightweight and apply the YAGNI (You Aren’t Gonna Need It) principle, adding only the features that you know you actually need. If it turns out you need some of the stickers that only Big Web Services can provide, you can always wrap your XML representations in SOAP envelopes, or cherry-pick the stickers you need and port them to HTTP headers. Given the proven scalability of the Web, starting simple is usually a safe choice—safe enough, I think, to be the default.

Chapter 11. Ajax Applications as REST Clients

From AJAX to Ajax

Every introduction to Ajax will tell you that it used to be AJAX, an acronym for Asynchronous JavaScript And XML. The acronym has been decommissioned and now Ajax is just a word. It’s worth spending a little time exploring why this happened. Programmers didn’t suddenly lose interest in acronyms. AJAX had to be abandoned because what it says isn’t necessarily true. Ajax is an architectural style that doesn’t need to involve JavaScript or XML.

So AJAX hackers decided to become Ajax hackers, rather than always having to explain that JavaScript needn’t mean JavaScript and XML might not be XML, or becoming Client-Side Scripting And Representation Format hackers. When I talk about Ajax in this book I mostly talk in terms of JavaScript and XML, but I’m not talking about those technologies: I’m talking about an application architecture.

The Ajax Architecture

1. A user, controlling a browser, makes a request for the main URI of an application.
2. The server serves a web page that contains an embedded script.
3. The browser renders the web page and either runs the script, or waits for the user to trigger one of the script’s actions with a keyboard or mouse operation.
4. The script makes an asynchronous HTTP request to some URI on the server. The user can do other things while the request is being made, and is probably not even aware that the request is happening.
5. The script parses the HTTP response and uses the data to modify the user’s view. This might mean using DOM methods to change the tag structure of the original HTML page. It might mean modifying what’s displayed inside a Flash application or Java applet.

The downside is that every application state has the same URI: the first one the end user visited. Addressability and statelessness are destroyed. The underlying web service may be addressable and stateless, but the end user can no longer bookmark a particular state, and the browser’s “Back” button stops working the way it should. The application is no longer on the Web, any more than a SOAP+WSDL web service that only exposes a single URI is on the Web. I discuss what to do about this later.

A del.icio.us Example

The Advantages of Ajax

This client also never explicitly parses the XML response from the del.icio.us web service. A web browser has an XML parser built in, and XMLHttpRequest automatically parses into a DOM object any XML document that comes in on a web service response. You access the DOM object through the XMLHttpRequest.responseXML member. The DOM standard for web browsers defines the API for this object: you can iterate over its children, search it with methods like getElementsByTagName, or hit it with XPath expressions.

The Disadvantages of Ajax

REST Goes Better

Making the Request

Handling the Response

JSON

Don’t Bogart the Benefits of REST

Cross-Browser Issues and Ajax Libraries

Subverting the Browser Security Model