Master REST: Core Concepts, HTTP Verbs, and Best Practices

REST (Representational State Transfer) is an architectural style that treats information as a first‑class citizen, enabling high performance, scalability, simplicity, and extensibility for web services.

1. Introduction

REST is a worldview, not a library; it emphasizes treating resources as primary and was popularized by Roy Fielding’s doctoral dissertation.

1.1 Basic Concepts

REST uses stateless communication, URLs as resource identifiers, and supports content negotiation via HTTP headers. http://fakelibrary.org/library Clients can request resources with GET, receive representations in XML, JSON, etc., and use POST, PUT, DELETE, HEAD, OPTIONS, PATCH for other operations.

2. REST vs SOAP

REST and SOAP solve different problems; they are not interchangeable. REST focuses on resource‑oriented design, while SOAP is suited for complex transactional scenarios.

3. Richardson Maturity Model

The model defines four levels of REST maturity, guiding incremental adoption of hypermedia controls and proper use of HTTP.

4. HTTP Verbs

GET

Retrieves a representation without modifying server state; safe and idempotent.

POST

Creates a new resource when the client cannot predict its identifier; not safe nor idempotent.

PUT

Replaces a resource at a known URI; idempotent.

DELETE

Removes a resource; should return 204 on success.

HEAD, OPTIONS, PATCH

HEAD checks metadata, OPTIONS discovers allowed methods, PATCH performs partial updates.

5. Response Codes

HTTP status codes are grouped into informational (1xx), success (2xx), redirection (3xx), client error (4xx), and server error (5xx). Examples include 200, 201, 204, 404, 500, and the humorous 418.

5.1 Resources and Specifications

Key specifications include RFC 3986 (URI), RFC 2616 (HTTP/1.1), and Fielding’s dissertation. Description languages such as RAML, Swagger, Apiary, and Hydra‑Cg help define APIs.

5.3 Implementations

Popular frameworks and libraries for building RESTful services include JAX‑RS, Restlet, NetKernel, Play, Spray, Express, Hapi, and Sinatra.

5.4 Clients

Tools for testing and consuming APIs are curl, httpie, and Postman.

6. Recommended Books

RESTful Web APIs – Richardson, Amundsen, Ruby

RESTful Web Services Cookbook – Allamaraju

REST in Practice – Webber, Parastatidis, Robinson

Restlet in Action – Louvel, Boileau

Resource‑Oriented Architecture Patterns – Sletten