URLs to the fore

David is right, put the URLs to the fore of any documentation of a RESTful API. The first thing i did when looking at the OpenSocial Data API documents was scan them to see what the URL patterns were. David provides a useful summary.

In general i recommend creating tables with URI templates, methods supported, content types produced/consumed and response codes returned. For extra bonus-points provide XPath expressions for XML representations that highlight the connected relationship to other resources. This really helps developers implementing the API and consumers. Or, use WADL with a style sheet as show by Mark Nottingham for the Yahoo news search.

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed
About

sandoz

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today