REST

You’ve heard of REST APIs. What are they? What is REST?

Definition

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:

Client-Server, to separate UI from data storage
Stateless Server, to improve reliability and scalability
Client Cache, to reduce some network traffic
Uniform Interface, to decouple implementations from the services they provide
Layered System, where each component is only concerned with those just below or just above it
Code-on-Demand, allowing client functionality to be extended by downloading applets or scripts

REST is an architectural style, NOT a product, NOT an API.

The World Wide Web is an example of a RESTful system.

Principles of REST

A RESTful system is characterized by

Addressable Resources
- Every resource has a (unique) identifier (e.g., a URI)
- Resources are generally nouns, so name your resources accordingly:
  - Example: http://www.yourcompany.com/products/2443
  - Non-example: http://www.yourcompany.com/getProduct?id=2443
- Resources are separate from their representations
Representation-Orientation
- Requests for resources return representations
- The representation contains the state of the resource
- The client can update or delete resources through their representations
Uniform, Constrained Interface
- Small, fixed number of verbs
- Example: HTTP has GET, PUT, POST, PATCH, DELETE, HEAD, OPTIONS, TRACE
- Non-example: Any RPC-based protocol such as SOAP or CORBA
Self-Descriptive Messages
- Messages include all the information necessary to be processed
- Example: Internet Media Types
Stateless Server
- With no shared context on the server, client requests are independent
- Servers can be simpler, multithreaded, easier to monitor, reliable, scalable, etc.
Cacheability
- Responses indicate whether the client can cache the data or not
- Reduces network traffic if the client knows it doesn't have to ask for the same data again
HATEOAS
- Hypermedia as the engine of application state
- Representations should include links to related resources
- Reduces the need for versioning by making most resources discoverable only from other resources

Writing RESTful Web Services

Thinking RESTfully

Remember when OOP was new?
- You had to shift your thinking from procedures to objects (from verbs to nouns): QueryOptimizer, ImageMapper, SiteInitializer, StringTokenizer, Enumerator, StreamReader, StreamWriter, Factory
- Transitioning from RPC to REST is the same thing!
Think: what are my resources?
- Examples: products, campaigns, customers, listings, profiles, lists, reviews, ads
- Resources do not have to be finely-grained. They do not have to correspond exactly to database tables.
Dealing with limited number of verbs
- Solution: Capture semantics with more resources (consider resource hierarchy)
- Commands, events, and actions can be resources too (but don't overdo this)

RESTful and non-RESTful URIs

RESTful:

  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

Non-RESTful:

  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

Use a framework

If you are writing a webapp back-end, you most certainly are using some kind of server-side product like Node for JavaScript, Flask for Python, Spring for Java, Rails for Ruby, or plain old PHP. Many of these products have a mechanism for making REST APIs easily. For Java, you can use a JAX-RS implementation such as Jersey or RestEasy.

REST and HTTP

HTTP is a stateless request-response protocol.

TODO IMAGE

Using HTTP Methods RESTfully

Request	Meaning
`GET /things`	Get all, or some of, the things. Use query parameters to restrict the set (i.e., do a search!), or to paginate.
`PUT /things`	Replace the set of all things. Put entire set in payload.
`POST /things`	Create a new thing. Server sets id. Put representation of new thing in payload.
`DELETE /things`	Delete all of the things.
`GET /things/8`	Get thing 8.
`PUT /things/8`	Replace thing 8 with new thing, but id stays 8. Put representation in payload. Or create a new thing with id 8.
`PATCH /things/8`	Edit a part of thing 8. Payload can have a description of what to change, or maybe just the fields needing changing.
`DELETE /things/8`	Delete thing 8.

You can implement OPTIONS yourself, too. HEAD will pretty much be handled by a framework.

Respect method constraints:

GET and HEAD should be safe (no user-requested resource modifications)
GET, HEAD, PUT, and DELETE should be idempotent (repeated requests same as one)

HTTP Request Headers

Request headers further refine the request. See Wikipedia’s list of headers for more information.

HTTP Responses

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:

Code	Meaning
400	Bad Request
401	Authorization Required
403	Forbidden
404	Not Found
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)
200	OK
201	Created (usually you should set the Location header for this)
202	Accepted (used for asynch requests)
204	No Content
301	Moved Permanently
409	Conflict
410	Gone

HTTP Response Headers

Response headers contain additional information about the response. See Wikipedia’s list of headers for more information.