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


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.

Principles of REST

A RESTful system is characterized by

Writing RESTful Web Services

Thinking RESTfully

RESTful and non-RESTful URIs



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.


HTTP is a stateless request-response protocol.


Using HTTP Methods RESTfully

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

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

Respect method constraints:

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:

400Bad Request
401Authorization Required
404Not Found
405Method Not Allowed (service doesn't support the requested method at that URI)
406Not Acceptable (server can't give back a representation in a requested format)
415Unsupported Media Type (server can't process the request body)
201Created (usually you should set the Location header for this)
202Accepted (used for asynch requests)
204No Content
301Moved Permanently

HTTP Response Headers

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:

How RESTful Is Your REST? from Abdelmonaim Remani