47
RESTful Service Best Practices
Table of Contents
Document History......................................................................................................................................5
Who Should Read This Document.............................................................................................................5
Introduction................................................................................................................................................6
What is REST?...........................................................................................................................................6
Uniform Interface..................................................................................................................................7
Resource-Based................................................................................................................................7
Manipulation of Resources Through Representations......................................................................7
Self-descriptive Messages................................................................................................................7
Hypermedia as the Engine of Application State (HATEOAS).........................................................7
Stateless.................................................................................................................................................7
Cacheable..............................................................................................................................................8
Client–server.........................................................................................................................................8
Layered system......................................................................................................................................8
Code on demand (optional)...................................................................................................................8
REST Quick Tips.......................................................................................................................................9
Use HTTP Verbs to Mean Something...................................................................................................9
Sensible Resource Names.....................................................................................................................9
XML and JSON.....................................................................................................................................9
Create Fine-Grained Resources...........................................................................................................10
Consider Connectedness......................................................................................................................10
Definitions................................................................................................................................................10
Idempotence........................................................................................................................................10
Safety...................................................................................................................................................11
HTTP Verbs..............................................................................................................................................11
GET.....................................................................................................................................................11
PUT.....................................................................................................................................................12
POST...................................................................................................................................................12
PUT vs POST for Creation..................................................................................................................13
DELETE..............................................................................................................................................13
Resource Naming.....................................................................................................................................14
Resource URI Examples.....................................................................................................................15
Resource Naming Anti-Patterns..........................................................................................................16
Pluralization.........................................................................................................................................16
Returning Representations.......................................................................................................................17
Resource Discoverability Through Links (HATEOAS cont'd)...........................................................18
Minimal Linking Recommendations..............................................................................................19
Link Format....................................................................................................................................19
Wrapped Responses.............................................................................................................................21
Handling Cross-Domain Issues...........................................................................................................22
Supporting CORS...........................................................................................................................22
Supporting JSONP..........................................................................................................................22
Querying, Filtering and Pagination..........................................................................................................23
05/29/12
www.RestApiTutorial.com
Page 3 of 34