Mastering REST: Core Concepts, HTTP Verbs, Status Codes and Tooling

1. Introduction

REST (Representational State Transfer) is an architectural style that treats information as a first‑class citizen, enabling high performance, scalability, simplicity, modifiability and extensibility. The concepts originate from Roy Fielding’s doctoral dissertation Architectural Styles and the Design of Network‑Based Software Architectures .

2. Core Concepts

2.1 What REST Means

REST is a worldview, not a library. It promotes stateless communication, uniform resource identifiers (URIs) and content negotiation. Resources are identified by URLs and can be accessed, created, updated or deleted via standard HTTP verbs.

2.2 URIs and URLs

RFC 1738 defines the URL scheme (e.g., http://fakelibrary.org/library). A URL is a concrete form of a URI that contains enough information for locating a resource.

2.3 Example Resource Endpoints

http://fakelibrary.org/library

– basic library information and search. http://fakelibrary.org/book – collection of books. http://fakelibrary.org/book/category/1234 – books filtered by category. http://fakelibrary.org/book/isbn/978-0596801687 – details of a specific book.

3. HTTP Verbs

3.1 GET

Retrieves a representation of a resource without side effects. Clients may request a specific media type via the Accept header. Example:

curl -H "Accept:application/json" http://fakelibrary.org/library

GET must be safe and idempotent.

3.2 POST

Creates a new resource when the server determines the identifier. Example:

curl -u user:pass -d @book.xml -H "Content-Type: text/xml" http://fakelibrary.org/book

On success the server returns HTTP 201 with a Location header. POST is neither safe nor idempotent.

3.3 PUT

Replaces the entire state of a known resource; it is idempotent. If the client knows the identifier, PUT can also be used to create the resource.

3.4 DELETE

Removes a resource. A successful delete returns HTTP 204. Re‑deleting a non‑existent resource should return HTTP 404 to avoid leaking existence information.

3.5 HEAD, OPTIONS, PATCH

HEAD checks metadata without transferring the body. OPTIONS discovers which verbs are supported for a resource. PATCH (standardised in 2010) applies partial updates and can be made idempotent with the If‑Match header.

4. HTTP Status Code Categories

HTTP status codes are grouped as follows:

1xx – informational

2xx – success (e.g., 200, 201, 204)

3xx – redirection

4xx – client errors (e.g., 400, 401, 404)

5xx – server errors (e.g., 500, 503)

5. Richardson Maturity Model

Leonard Richardson defines four levels of REST maturity, from simple URI exposure (Level 0) to full hypermedia controls (Level 3). Moving from Level 2 to Level 3 usually involves adopting a new MIME type for hypermedia.

6. API Description Languages

RAML – YAML/JSON based, supports Level 2 APIs ( http://raml.org)

Swagger – similar capabilities with code generators ( http://swagger.io)

Apiary.io – collaborative Markdown‑based API design ( http://apiary.io)

Hydra‑CG – JSON‑LD driven hypermedia description ( http://www.hydra-cg.com)

7. Server‑Side Implementations

JAX‑RS ( https://jax-rs-spec.java.net)

Restlet ( http://restlet.org)

NetKernel ( http://netkernel.org)

Play Framework ( https://www.playframework.com)

Spray ( http://spray.io)

Express ( http://expressjs.com)

hapi ( http://hapijs.com)

Sinatra ( http://www.sinatrarb.com)

8. Client Tools

curl – command‑line tool supporting many protocols ( https://curl.haxx.se)

httpie – user‑friendly HTTP client ( https://httpie.org)

Postman – desktop application for request capture, replay and authentication ( https://www.getpostman.com)

9. References

Fielding dissertation: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

RFC 3986 (URI syntax): http://www.ietf.org/rfc/rfc3986.txt

RFC 2616 (HTTP/1.1): http://www.ietf.org/rfc/rfc2616.txt

JSON Patch (RFC 6902): https://www.ietf.org/rfc/rfc6902.txt

XML Patch (RFC 7351): https://www.ietf.org/rfc/rfc7351.txt

Note: Promotional links and unrelated content have been omitted.