REST Architectural Style

This post is a concept explanation of REST – including exam questions and tags.

In a Nutshell

REST is an architectural style for distributed hypermedia systems based on HTTP. Core idea: resources are addressed via URIs, manipulated with standardized methods, and transferred via representations.

Compact Technical Description

REST defines six constraints: Client-Server, Statelessness, Cacheability, Uniform Interface, Layered, optionally Code on Demand. Resources are business objects uniquely identified per URI (e.g., https://api.shop.de/orders/42). Representations transport state, typically JSON or XML, negotiated via Content Negotiation using Accept and Content-Type. Methods have semantics: GET is safe/idempotent, POST not idempotent, PUT idempotent, PATCH not necessarily idempotent, DELETE idempotent. Status codes signal results (200, 201, 204, 400, 401, 403, 404, 409, 500). HATEOAS embeds navigation and action links in representations. Efficient caching uses Cache-Control, ETag, Last-Modified, and conditional requests.

Exam-Relevant Key Points

• Resource-oriented API design, nouns/plural, stable URIs, no verbs in paths
• HTTP methods and semantics, safe/idempotent/non-idempotent, mapping to CRUD
• Define idempotency cleanly, especially for PUT, DELETE, POST with Idempotency Key
• Use status codes purposefully, 2xx/3xx/4xx/5xx, Location header with 201
• Requirements for data protection, logging, traceability, document error codes
• Enforce TLS, OAuth 2/OIDC, JWT, CORS, Rate Limiting, Input Validation, Logging
• Loose coupling, reusability, independent evolution of client and server
• OpenAPI documentation, example requests/responses, error catalog, versioning strategy

Core Components

1. Resource and URI Design
2. Representations, Media Types and Schema
3. Method Semantics: GET, POST, PUT, PATCH, DELETE
4. Status Codes and Headers
5. Content Negotiation: Accept, Content-Type, Accept-Language
6. Caching: Cache-Control, ETag, Last-Modified, Conditional Requests
7. Security: Authentication, Authorization, TLS, CORS
8. Versioning: URI, Header, Content-Types
9. Observability: Logging, Metrics, Tracing, Correlation-ID
10. Testing Procedures: Contract Tests, API Tests, Error Paths, Idempotency Tests

Practical Example

// Example: Order resource with HATEOAS and Idempotency
Resources:
GET /orders - List of orders
POST /orders - create new order
GET /orders/{order-id} - Read single order
PUT /orders/{order-id} - Replace order completely
PATCH /orders/{order-id} - Partially modify order
DELETE /orders/{order-id} - Delete order

Example POST request:
{
  "customerId": 12345,
  "items": [{ "sku": "A1", "qty": 2 }]
}

Response 201 Created, Header: Location: https://api.shop.de/orders/42
Body:
{
  "order-id": 42,
  "status": "created",
  "links": [
    { "rel": "self", "href": "https://api.shop.de/orders/42" },
    { "rel": "confirm", "method": "POST", "href": "https://api.shop.de/orders/42/confirm" }
  ]
}

Idempotency with POST: Client additionally sends Idempotency-Key: abc-123.
Server stores result per key, delivers same response on retry.

Advantages and Disadvantages

Advantages

• Interoperability through standards
• Loose coupling, good scalability through statelessness
• Efficient caching, clear error signals via status codes
• Simple usage through browsers and tools

Disadvantages

• Overfetching and underfetching possible
• Complex write processes require clean idempotency and transaction strategies
• HATEOAS often neglected
• Security responsibility lies heavily with API design
• Chatty APIs increase latencies

Typical Exam Questions (with Brief Answers)

1. Six REST constraints and their effect? Client-Server (independent development), Stateless (no session states), Cacheable (repeated responses efficient), Uniform Interface (standardized methods), Layered (intermediaries possible), Code on Demand (optional scripts).
2. PUT vs. PATCH with idempotency? PUT replaces completely and is idempotent, PATCH modifies partially and is not necessarily idempotent.
3. Safe for HTTP methods? Safe = no state-changing side effects, GET and HEAD are safe (read-only).
4. ETag and conditional requests? Server delivers ETag, client sends If-None-Match, on equality server responds with 304 Not Modified without body.
5. Version REST API? URI versioning (/v1), header-based, Accept-based (application/vnd.firma.resource.v2+json), important: backward-compatible changes.
6. HATEOAS and benefits? Client discovers actions via links in representations, reduces coupling and hard assumptions about workflows.
7. Content Negotiation in practice? Client sends Accept (application/json), server selects appropriate representation or responds with 406 Not Acceptable.
8. Idempotent write operations for payments? POST on collection resource with Idempotency Key, dedicated transaction resource, retries with same key deliver same end state:

/payments/{payment-id}

Most Important Sources

1. https://roy.gbiv.com/untangled
2. https://www.rfc-editor.org/rfc/rfc9110
3. https://learn.microsoft.com/azure/architecture/best-practices/api-design