REST, or Representational State Transfer, is an architectural style for distributed systems defining certain constraints that provide efficiency, scalabilty, and other desirable attributes.
REST was introduced by Roy Fielding. The constraints he identified were:
REST is an architectural style, NOT a product, NOT an API.
The World Wide Web is an example of a RESTful system.
A RESTful system is characterized by
http://example.com/profiles http://example.com/profiles?what=pizza&where=90069&page=4&rpp=20 http://example.com/profiles/2734 http://example.com//twitter-handles/jp http://example.com/providers/2345/budgets/4567
http://example.com/order-system?op=deleteCustomer&id=2 http://example.com/find-events?where=90069&after=2010-05-20 http://example.com/api/products/update?id=3&name=mouse
HTTP is a stateless request-response protocol.TODO IMAGE
|Get all, or some of, the things. Use query parameters to restrict the set (i.e., do a search!), or to paginate.|
|Replace the set of all things. Put entire set in payload.|
|Create a new thing. Server sets id. Put representation of new thing in payload.|
|Delete all of the things.|
|Get thing 8.|
|Replace thing 8 with new thing, but id stays 8. Put representation in payload. Or create a new thing with id 8.|
|Edit a part of thing 8. Payload can have a description of what to change, or maybe just the fields needing changing.|
|Delete thing 8.|
You can implement OPTIONS yourself, too. HEAD will pretty much be handled by a framework.
Respect method constraints:
Request headers further refine the request. See Wikipedia’s list of headers for more information.
Use response codes as they were intended to be used. The ones you should be aware of (that is, that you may set yourself as part of your application) are:
|405||Method Not Allowed (service doesn't support the requested method at that URI)|
|406||Not Acceptable (server can't give back a representation in a requested format)|
|415||Unsupported Media Type (server can't process the request body)|
|201||Created (usually you should set the Location header for this)|
|202||Accepted (used for asynch requests)|
Response headers contain additional information about the response. See Wikipedia’s list of headers for more information.
Start with these if you are new:
Ready for something more hardcore?
Here’s an old but good presentation: