What is REST?

REST stands for REpresentational State Transfer.

REST is a system that allows users to request information from a server via an API and then receive appropriate responses in different data formats.

The responses themselves are resource representations, such as a list of Github commits or weather forecasts, that can be delivered as XML or JSON strings.

In a typical REST architecture, a client sends a request to the server, which responds with a representation of the requested resource.

This requested resource is usually an informational object, like a database or a document, and its representation is usually a formatted document (often XML or JSON) that carries the result of the requested resource as well as its state

REST resources are typically identified using meaningful URLs that accept different request “verbs”—GET, POST, PUT, and DELETE. These verbs are somewhat analogous to the create-retrieve- update-delete (CRUD) model that many developers are familiar with.

For example, if you want to retrieve data safely (in other words, with idempotence, or not changing anything while doing so), you would use a GET request.

If you want to create data, use a POST request; to update data, use a PUT request; and finally, to delete data, use a DELETE request.

Another important factor to consider is the response. A RESTful service typically provides two meaningful components in its responses: the response body itself and a status code.

Many REST servers actually allow users to specify a response format (such as JSON, XML, CSV, serialized PHP, or plain text) either by sending in an ACCEPT parameter or by specifying a file extension (for example, /api/users.xml or /api/users.json).

Other REST servers, like the one you’re going to implement here, have hard-coded response formats. These are equally acceptable as long as they are documented.

Response codes tend to be HTTP status codes. The beauty of this schema is that you can use existing, well-known status codes to identify errors or successes.

A 201 status code (CREATED) is a perfect response to a successful POST request.

A 500 error code indicates a failure on your end, but a 400 error code indicates a failure on the client’s end (BAD REQUEST).

Send a 503 (SERVICE UNAVAILABLE) if something is wrong with the server.

See list of status codes