RESTful Web Services by Ruby, Sam, Richardson, Leonard -- Read -- Imperial Library of Trantor

Index

RESTful Web Services

SPECIAL OFFER: Upgrade this ebook with O’Reilly A Note Regarding Supplemental Files Foreword Preface

The Web Is Simple Big Web Services Are Not Simple The Story of the REST Reuniting the Webs What’s in This Book? Administrative Notes Conventions Used in This Book Using Code Examples Safari® Enabled How to Contact Us Acknowledgments

1. The Programmable Web and Its Inhabitants

Kinds of Things on the Programmable Web HTTP: Documents in Envelopes Method Information Scoping Information The Competing Architectures

RESTful, Resource-Oriented Architectures RPC-Style Architectures REST-RPC Hybrid Architectures The Human Web Is on the Programmable Web

Technologies on the Programmable Web

HTTP URI XML-RPC SOAP WS-* WSDL WADL

Leftover Terminology

2. Writing Web Service Clients

Web Services Are Web Sites

Wrappers, WADL, and ActiveResource

del.icio.us: The Sample Application

What the Sample Clients Do

Making the Request: HTTP Libraries

Optional Features Ruby: rest-open-uri and net/http Python: httplib2 Java: HttpClient C#: System.Web.HTTPWebRequest PHP: libcurl JavaScript: XMLHttpRequest The Command Line: curl Other Languages

Processing the Response: XML Parsers

Ruby: REXML, I Guess Python: ElementTree Java: javax.xml, Xerces, or XMLPull C#: System.Xml.XmlReader PHP JavaScript: responseXML Other Languages

JSON Parsers: Handling Serialized Data Clients Made Easy with WADL

3. What Makes RESTful Services Different?

Introducing the Simple Storage Service Object-Oriented Design of S3

A Few Words About Buckets A Few Words About Objects What If S3 Was a Standalone Library?

Resources HTTP Response Codes An S3 Client

The Bucket List The Bucket The S3 Object

Request Signing and Access Control

Signing a URI Setting Access Policy

Using the S3 Client Library Clients Made Transparent with ActiveResource

Creating a Simple Service An ActiveResource Client A Python Client for the Simple Service

Parting Words

4. The Resource-Oriented Architecture

Resource-Oriented What Now? What’s a Resource? URIs

URIs Should Be Descriptive The Relationship Between URIs and Resources

Addressability Statelessness

Application State Versus Resource State

Representations

Deciding Between Representations

Links and Connectedness The Uniform Interface

GET, PUT, and DELETE HEAD and OPTIONS POST

Creating subordinate resources Appending to the resource state Overloaded POST: The not-so-uniform interface

Safety and Idempotence

Safety Idempotence Why safety and idempotence matter

Why the Uniform Interface Matters

That’s It!

5. Designing Read-Only Resource-Oriented Services

Resource Design Turning Requirements Into Read-Only Resources Figure Out the Data Set

General Lessons

Split the Data Set into Resources

General Lessons

Name the Resources

Encode Hierarchy into Path Variables No Hierarchy? Use Commas or Semicolons

Map URIs Scale

Algorithmic Resource? Use Query Variables URI Recap

Design Your Representations

The Representation Talks About the State of the Resource The Representation Links to Other States Representing the List of Planets Representing Maps and Points on Maps Representing the Map Tiles Representing Planets and Other Places Representing Lists of Search Results

Link the Resources to Each Other The HTTP Response

What’s Supposed to Happen?

Conditional HTTP GET

What Might Go Wrong?

Conclusion

6. Designing Read/Write Resource-Oriented Services

User Accounts as Resources

Why Should User Accounts Be Resources? Authentication, Authorization, Privacy, and Trust Turning Requirements into Read/Write Resources Figure Out the Data Set Split the Data Set into Resources Name the Resources with URIs Expose a Subset of the Uniform Interface Design the Representation(s) Accepted from the Client Design the Representation(s) to Be Served to the Client Link This Resource to Existing Resources What’s Supposed to Happen? What Might Go Wrong?

Custom Places

Figure Out the Data Set Split the Data Set into Resources Name the Resources with URIs Expose a Subset of the Uniform Interface Design the Representation(s) Accepted from the Client Design the Representation(s) Served to the Client Link This Resource to Existing Resources What’s Supposed to Happen? What Might Go Wrong?

A Look Back at the Map Service

7. A Service Implementation

A Social Bookmarking Web Service Figuring Out the Data Set Resource Design

REST in Rails The User Controller The Bookmarks Controller The User Tags Controller The Calendar Controller The URI Controller The Recent Bookmarks Controller The Bundles Controller The Leftovers Remodeling the REST Way Implementation: The routes.rb File

Design the Representation(s) Accepted from the Client Design the Representation(s) Served to the Client Connect Resources to Each Other What’s Supposed to Happen? What Might Go Wrong? Controller Code

What Rails Doesn’t Do

Conditional GET param[:id] for things that aren’t IDs

The ApplicationController The UsersController The BookmarksController The TagsController The Lesser Controllers

The CalendarController The RecentController The UrisController

Model Code

The User Model The Bookmark Model

What Does the Client Need to Know?

Natural-Language Service Description Description Through Standardization Hypermedia Descriptions

8. REST and ROA Best Practices

Resource-Oriented Basics The Generic ROA Procedure Addressability

Representations Should Be Addressable

State and Statelessness Connectedness The Uniform Interface

Safety and Idempotence New Resources: PUT Versus POST Overloading POST

This Stuff Matters

Why Addressability Matters Why Statelessness Matters Why the Uniform Interface Matters Why Connectedness Matters

A terrifying example

Resource Design

Relationships Between Resources Asynchronous Operations Batch Operations Transactions When In Doubt, Make It a Resource

URI Design Outgoing Representations Incoming Representations Service Versioning Permanent URIs Versus Readable URIs Standard Features of HTTP

Authentication and Authorization

Basic authentication Digest authentication WSSE username token

Compression Conditional GET Caching

Please cache Thank you for not caching Default caching rules

Look-Before-You-Leap Requests Partial GET

Faking PUT and DELETE The Trouble with Cookies Why Should a User Trust the HTTP Client?

Applications with a Web Interface Applications with No Web Interface What Problem Does this Solve?

9. The Building Blocks of Services

Representation Formats

XHTML XHTML with Microformats Atom

OpenSearch

SVG Form-Encoded Key-Value Pairs JSON RDF and RDFa Framework-Specific Serialization Formats Ad Hoc XHTML Other XML Standards and Ad Hoc Vocabularies Encoding Issues

XML and HTTP: Battle of the encodings The character encoding of a JSON document

Prepackaged Control Flows

General Rules Database-Backed Control Flow

GET PUT POST for creating a new resource POST for appending to a resource DELETE

The Atom Publishing Protocol

Collections Members Service document Category documents Binary documents as APP members Summary

GData

Querying collections Data extensions

POST Once Exactly

Hypermedia Technologies

URI Templates XHTML 4

XHTML 4 links XHTML 4 forms Shortcomings of XHTML 4

XHTML 5 WADL

Describing a del.icio.us resource Describing an APP collection Is WADL evil?

10. The Resource-Oriented Architecture Versus Big Web Services

What Problems Are Big Web Services Trying to Solve? SOAP

The Resource-Oriented Alternative

WSDL

The Resource-Oriented Alternative

UDDI

The Resource-Oriented Alternative

Security

The Resource-Oriented Alternative

Reliable Messaging

The Resource-Oriented Alternative

Transactions

The Resource-Oriented Alternative

BPEL, ESB, and SOA Conclusion

11. Ajax Applications as REST Clients

From AJAX to Ajax The Ajax Architecture A del.icio.us Example The Advantages of Ajax 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

Prototype Dojo

Subverting the Browser Security Model

Request Proxying JavaScript on Demand

Dynamically writing the script tag Library support

12. Frameworks for RESTful Services

Ruby on Rails

Routing Resources, Controllers, and Views Outgoing Representations Incoming Representations Web Applications as Web Services The Rails/ROA Design Procedure

Restlet

Basic Concepts Writing Restlet Clients Writing Restlet Services

Resource and URI design Request handling and representations Compiling, running, and testing

Conclusion

Django

Create the Data Model Define Resources and Give Them URIs Implement Resources as Django Views

The bookmark list view The bookmark detail view Further directions

Conclusion

A. Some Resources for REST and Some RESTful Resources

Standards and Guides

HTTP and URI RESTful Architectures Hypermedia Formats Frameworks for RESTful Development Weblogs on REST

Services You Can Use

Service Directories Read-Only Services Read/Write Services

B. The HTTP Response Code Top 42

Three to Seven Status Codes: The Bare Minimum 1xx: Meta

100 (“Continue”) 101 (“Switching Protocols”)

2xx: Success

200 (“OK”) 201 (“Created”) 202 (“Accepted”) 203 (“Non-Authoritative Information”) 204 (“No Content”) 205 (“Reset Content”) 206 (“Partial Content”) 207 (“Multi-Status”)

3xx: Redirection

300 (“Multiple Choices”) 301 (“Moved Permanently”) 302 (“Found”) 303 (“See Other”) 304 (“Not Modified”) 305 (“Use Proxy”) 306: Unused 307 (“Temporary Redirect”)

4xx: Client-Side Error

400 (“Bad Request”) 401 (“Unauthorized”) 402 (“Payment Required”) 403 (“Forbidden”) 404 (“Not Found”) 405 (“Method Not Allowed”) 406 (“Not Acceptable”) 407 (“Proxy Authentication Required”) 408 (“Request Timeout”) 409 (“Conflict”) 410 (“Gone”) 411 (“Length Required”) 412 (“Precondition Failed”) 413 (“Request Entity Too Large”) 414 (“Request-URI Too Long”) 415 (“Unsupported Media Type”) 416 (“Requested Range Not Satisfiable”) 417 (“Expectation Failed”)

5xx: Server-Side Error

500 (“Internal Server Error”) 501 (“Not Implemented”) 502 (“Bad Gateway”) 503 (“Service Unavailable”) 504 (“Gateway Timeout”) 505 (“HTTP Version Not Supported”)

C. The HTTP Header Top Infinity

Standard Headers

Accept Accept-Charset Accept-Encoding Accept-Language Accept-Ranges Age Allow Authorization Cache-Control Connection Content-Encoding Content-Language Content-Length Content-Location Content-MD5 Content-Range Content-Type Date ETag Expect Expires From Host If-Match If-Modified-Since If-None-Match If-Range If-Unmodified-Since Last-Modified Location Max-Forwards Pragma Proxy-Authenticate Proxy-Authorization Range Referer Retry-After TE Trailer Transfer-Encoding Upgrade User-Agent Vary Via Warning WWW-Authenticate

Nonstandard Headers

Cookie POE POE-Links Set-Cookie Slug X-HTTP-Method-Override X-WSSE

Index About the Authors Colophon SPECIAL OFFER: Upgrade this ebook with O’Reilly

← Prev
Back
Next →

← Prev
Back
Next →