Help
Have you just created the ultimate RESTful interface for a revolutionary new web service and now want to document it? Good thing there's this excerpt from Subbu Allamaraju's RESTful Web Services Cookbook to clue you in on what it will take to get the job done.
The best way to promote design- and development-time discoverability is to unambiguously document the information needed to implement clients.
Fully describe the following in human-readable documentation:
All resources and methods supported for each resource
Media types and representation formats for resources in requests and responses
Each link relation used, its business significance, HTTP method to be used, and resource that the link identifies
All fixed URIs that are not supplied via links
Query parameters used for all fixed URIs
URI templates and token substitution rules
Authentication and security credentials for accessing resources
For XML representations, if your clients and servers are capable of supporting XML schemas, use a schema language as a “convention” to describe the structure of XML documents used for representations in requests and responses. For other formats, use conventions to describe representations in prose.
No machine-readable description can replace human-readable documentation. Documenting your web service in human-readable format such as HTML is the most useful way to enable design-time discovery. When documenting your service, include all the information necessary to implement a client.
Tip
Lack of a standard description language is often cited as a limitation of REST. In reality, machine-readable description languages do not communicate the semantics necessary for client developers to write code. See, for examples, the documentation of web services by Yahoo! (http://developer.yahoo.com), Flickr (http://www.flickr.com/services/api/), Twitter (http://apiwiki.twitter.com/), and Google Data Protocol (http://code.google.com/apis/gdata/). All these services provide extensive human-readable documentation with examples.
Here is an example of what to include when documenting a RESTful web service. Consider the album example from the section called “How to Merge Resources” to support finding, creating, editing, duplicating, and merging albums. Tables 14.1, 14.2, and 14.3 illustrate how to document such a web service.
Table 14.1. Resources
| Resource | Methods | Description |
|---|---|---|
| Photo | GET, PUT | This resource contains photo metadata and a link to a related binary photo media resource (such as a JPEG file). Media types:
|
| Photo media | GET, PUT | This resource represents the uploaded photo. Submit
a Media
types: |
| Album | GET, DELETE, and
POST | This resource contains zero or more photos. Use
Media types: |
| Album collection | GET, DELETE, and
POST | This resource contains zero or more albums. Use
Media types:
|
| Duplicate album controller | POST | This resource lets a client duplicate an album. Media types:
|
| Merge album controller | GET and POST | This resource lets a client merge albums. Media types:
|
Table 14.2. URIs
| Resource | URI | Description |
|---|---|---|
| Album collection | http://www.example.org/albums | Use this URI to get the 10 latest albums using
Use links with the relation
types |
| Album search | http://www.example.o...ym={year-month} | Use this URI template to search for albums. The token http://www.example.o...ums?q=paris&ym= http://www.example.o...king&ym=2009-08 http://www.example.o...bums?q=&ym=2000 |
| Album merge | http://www.example.o...1}&src={srcid2} | Use this template to get a link to merge two albums into a new album. The server will delete the original albums after this operation. This operation cannot undone. In this template, the tokens |
Table 14.3. Link relation types
| Name | Description |
|---|---|
http://www.example.org/rels/duplicate | Use a link with this relation type to submit a
|
http://www.example.org/rels/merge | Use a link with this relation type to refer to a controller resource to merge albums. |
For the sake of brevity, the previous documentation excludes details of the XML documents and form parameters used.
Learn more about this topic from RESTful Web Services Cookbook.
While the REST design philosophy has captured the imagination of web and enterprise developers alike, using this approach to develop real web services is no picnic. This cookbook includes more than 100 recipes to help you take advantage of REST, HTTP, and the infrastructure of the Web. You'll learn ways to design RESTful web services for client and server applications that meet performance, scalability, reliability, and security goals, no matter what programming language and development framework you use.
