1. Introduction

REST stands for Representational State Transfer. It relies on a stateless, client-server, cacheable communications protocol. REST is an architectural style for designing networked applications. RESTful applications use HTTP requests to post and put data (create and/or update), read data (make queries), and delete data. Thus, REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations (see table table 1). When building web services the use of REST is often preferred over the more heavyweight SOAP (Simple Object Access Protocol) style because REST is less complex and does not leverage as much bandwidth, which makes it a better fit for use over the Internet.

Table 1. CRUD/HTTP/SQL Mapping
CRUD Operation HTTP Method SQL Statement Idempotent? Safe?

Create

POST

INSERT

No

No

Read

GET

SELECT

Yes

Yes

Update

PUT

UPDATE

Yes

No

Delete

DELETE

DELETE

Yes

No

We say an operation is idempotent if it can be applied multiple times without changing the result beyond the initial application. For example, in mathematics the absolute value is an idempotent operation: applying it once or multiple times gives us the same answer.

An operation is safe if it’s only used for data retrieval (it doesn’t have any side-effects on the server).

REST was defined by Roy Thomas Fielding in his 2000 PhD dissertation “Architectural Styles and the Design of Network-based Software Architectures”.

2. API Guidelines

REST is more a collection of principles than it is a set of standards. There are “best practices” and de-facto standards but those are constantly evolving. Fortunately for us, there are a couple of documents, both written by Todd Fredrich, that provide some useful guidelines on things to consider when writing RESTful APIs:

These are the recommendations we’ll be using:

  1. We’ll use a noun to name our resource, not a verb, and it will be in plural form ('employees' instead of 'employee').

  2. We’ll use the Collection Metaphor. This means that our resource is going to have two endpoints:

    • '/employees' — for the complete resource collection.

    • '/employees/{ID}' — for each individual resource within the collection.

  3. We’ll supply links in the response body for retrieval of the resource object itself or related objects. This is a constraint of the REST application architecture known as HATEOAS (Hypermedia as the Engine of Application State).

  4. We’ll use HTTP methods to mean something useful:

    • GET — Read a resource or collection.

    • POST — Create.

    • PUT — Update.

    • DELETE — Remove a resource or collection.

  5. We’ll make sure that the GET, PUT and DELETE operations are idempotent.

  6. We’ll use the JSON format for the request and response bodies.

  7. We’ll use meaningful HTTP status codes:

    • 200 — OK. The request was successful.

    • 201 — Created. New resource was created successfully.

    • 400 — Bad Request. Malformed syntax or a bad query.

    • 404 — Not Found. Requested resource does not exist.