REST API Basics

Introduction

REST (Representational State Transfer) is a set of conventions for building HTTP APIs around resources. A well-designed REST API is intuitive, cacheable, and discoverable.

Understanding the topic

The REST cheat-sheet:

• Nouns, not verbs: /orders, not /getOrders.
• HTTP method = action: GET (read) · POST (create) · PUT (replace) · PATCH (partial) · DELETE.
• Status codes matter: 200 OK · 201 Created · 204 No Content · 400 Bad Request · 401 · 403 · 404 · 409 · 422 · 500.
• Plural collections: /users/42/orders.
• Idempotency: GET / PUT / DELETE are idempotent; POST is not.
• Pagination: ?page=0&size=20 + Link headers or wrapped {content,page}.

Syntax reference

A reference resource design:

GET    /api/v1/orders           list (paged, filterable)
POST   /api/v1/orders           create  → 201 + Location header
GET    /api/v1/orders/{id}      read
PUT    /api/v1/orders/{id}      full replace (idempotent)
PATCH  /api/v1/orders/{id}      partial update
DELETE /api/v1/orders/{id}      remove  → 204

GET    /api/v1/orders/{id}/items   sub-resource
POST   /api/v1/orders/{id}/cancel  action verb (allowed when verbs are unavoidable)