REST

REpresentational State Transfer (REST) is a style of web service architecture designed to map create, read, update, and delete operations with their corresponding HTTP verbs.

HTTP was originally intended to allow web browsers to display HTML content hosted on web-servers. The ubiquity of HTTP has lead to its adoption by other user agents. Web services are APIs build on top of HTTP, designed to be consumed by other software.

Early web services like SOAP (Simple Object Access Protocol) used HTTP as a transport mechanism for remote procedure calls encoded as XML. SOAP services fell out of favor because they frequently proved to be complex, fragile, and opaque. As JSON gained in popularity, so did REST-ful APIs, since the resource-based philosophy mapped more naturally to HTTP operations.

Imagine you were building a web service to allow maintenance of this glossary. A REST-ful API would permit the following operations:

Method Example URL Description
GET http://api.hacksplaining.com/glossary Retrieve a list of glossary pages in JSON.
POST http://api.hacksplaining.com/glossary Create a new glossary page, described as JSON in the POST body.
GET http://api.hacksplaining.com/glossary/rest Retrieve details on the "REST" glossary page.
PUT http://api.hacksplaining.com/glossary/rest Update details on the "REST" glossary page.
DELETE http://api.hacksplaining.com/glossary/rest Delete the "REST" glossary page.

With the increasing popularity of rich web applications, many developers choose to model the APIs used by their AJAX code as REST-ful APIs too.

Following REST-ful design principles ensures that your API is clearly defined and intuitive to anyone using it. REST-ful APIs are also accessible in a browser environment, which as well as making them easily testable with browser plug-ins, means they can be used in client-side code.

REST APIs are typically stateless -- the server does not keep track of which client is making requests. This helps greatly with scaling out a web service.