REST Architectural Style

This post is a conceptual overview of REST, complete with exam questions and key takeaways.

In a Nutshell

REST is an architectural style for distributed hypermedia systems built on HTTP. The core idea: resources are addressed via URIs, manipulated using standardized methods, and transferred through representations.

Technical Overview

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

Exam-Relevant Points

• Resource-oriented API design: nouns, plural forms, stable URIs, no verbs in paths
• HTTP methods and semantics: safe/idempotent/non-idempotent, mapping to CRUD
• Idempotency defined rigorously, especially for PUT, DELETE, and POST with Idempotency Key
• Status codes used strategically: 2xx/3xx/4xx/5xx, Location header on 201
• Requirements for privacy, logging, auditability, and documented error codes
• TLS enforcement, 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: 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 entirely
PATCH /orders/{order-id} - partial update to 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 includes an Idempotency-Key: abc-123 header.
Server stores the result per key and returns the same response on retry.

Strengths and Weaknesses

Strengths

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

Weaknesses

• Overfetching and underfetching are possible
• Complex write operations require careful idempotency design and transaction strategies
• HATEOAS is often overlooked
• Security responsibility falls heavily on API design
• Chatty APIs can suffer from increased latency

Common Exam Questions (with Brief Answers)

1. What are the six REST constraints and their effect? Client-Server (independent evolution), Stateless (no session state), Cacheable (efficient caching of repeated responses), Uniform Interface (standardized methods), Layered (intermediaries possible), Code on Demand (optional scripts).

2. PUT versus PATCH regarding idempotency? PUT replaces the entire resource and is idempotent; PATCH applies partial updates and is not necessarily idempotent.

3. What does “safe” mean for HTTP methods? Safe means no state-changing side effects. GET and HEAD are safe—they only read data.

4. ETags and conditional requests? Server returns an ETag; client sends If-None-Match. If they match, the server responds with 304 Not Modified and no body.

5. How do you version a REST API? URI versioning (/v1), header-based, or Accept-based (application/vnd.firma.resource.v2+json). Important: maintain backward-compatible changes.

6. HATEOAS and its benefits? Clients discover actions through links in representations, reducing coupling and hard-coded assumptions about workflows.

7. Content Negotiation in practice? Client sends Accept (application/json); server chooses the appropriate representation or responds with 406 Not Acceptable.

8. Idempotent write operations for payments? POST to a collection resource with an Idempotency Key, or use a dedicated transaction resource. Retries with the same key deliver the same outcome:

/payments/{payment-id}

Key Resources

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