Jump to content

How to Document RESTful Web Services

  adfm's Photo
Posted Apr 22 2010 03:19 PM

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.


You want to know how to document your web service.


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.


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


This resource contains photo metadata and a link to a related binary photo media resource (such as a JPEG file).

Media types: application/xml

Photo mediaGET, PUT

This resource represents the uploaded photo. Submit a POST request with media type multipart/form-data to the album resource to create a photo and a photo media resource.

Media types: image/jpeg, image/gif, image/png


This resource contains zero or more photos. Use POST to add photos to an album.

Media types: application/xml, multipart/form-data

Album collectionGET, DELETE, and POST

This resource contains zero or more albums. Use POST to add a new album to the collection.

Media types: application/xml

Duplicate album controllerPOST

This resource lets a client duplicate an album.

Media types: application/xml

Merge album controllerGET and POST

This resource lets a client merge albums.

Media types: application/xml

Table 14.2. URIs

Album collectionhttp://www.example.org/albums

Use this URI to get the 10 latest albums using GET or to create a new album using POST.

Use links with the relation types next and previous to browse through all the albums.

Album searchhttp://www.example.o...ym={year-month}

Use this URI template to search for albums.

The token {keyword} takes a keyword, and the token {year-month} takes either a year or a year and month. Here are some example URIs after token substitution:



Album mergehttp://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 {srcid1} and srcid2 are identifiers of the albums to be merged.

Table 14.3. Link relation types


Use a link with this relation type to submit a POST request to duplicate an existing album.


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.

RESTful Web Services Cookbook

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.

See what you'll learn

0 Subscribe

2 Replies

  Ramprasad G's Photo
Posted Jun 03 2012 08:42 AM

What about documenting using WSDL ?

  rmorschel's Photo
Posted Jul 31 2012 07:02 AM

IG Group have just open-sourced RESTdoclet, which generates documentation for RESTful services built using the Spring REST framework. More info here: http://soaprobe.blog...tion-using.html