REST APIs Explained: Architectural Constraints, HTTP Semantics, and Production Standards

Representational State Transfer (REST) is an architectural style for distributed hypermedia systems first introduced by Roy Fielding in his 2000 doctoral dissertation. Today, RESTful APIs serve as the primary communication backbone connecting browser applications, mobile clients, and backend microservices across the global technology ecosystem.

Despite its ubiquity, many production APIs violate fundamental REST conventions—frequently confusing RPC-style URL actions with RESTful resource representations, misusing HTTP status codes, or mishandling idempotency during network retries.

This guide provides a rigorous, practical reference for designing resilient RESTful APIs, examining architectural constraints, resource modeling, PATCH idempotency semantics, RFC 9457 problem details, pagination patterns, authentication strategies, and URI versioning.

1. The Six Foundational Architectural Constraints of REST

An API is not "RESTful" simply because it sends JSON over HTTP. According to Fielding's architectural definition, a system must adhere to six specific constraints:

1. Client-Server Separation: User interface concerns are decoupled from data storage concerns. Clients do not manage database state; servers do not manage UI layout rendering.
2. Statelessness: Each request from client to server must contain all the contextual information required to understand and authorize the transaction. The server maintains no client session state between requests.
3. Cacheability: Responses must explicitly declare themselves as cacheable or non-cacheable (via Cache-Control and ETag headers) to prevent clients from reusing stale data.
4. Uniform Interface: The cornerstone of REST. Resources are identified using standardized URIs, manipulated through self-describing representations, and accompanied by metadata.
5. Layered System: A client cannot tell whether it is communicating directly with the origin server or through an intermediary reverse proxy, CDN, API gateway, or load balancer.
6. Code on Demand (Optional): Servers may temporarily extend client capabilities by transmitting executable scripts (such as JavaScript or WebAssembly).

2. Resource-Oriented URI Design Conventions

A foundational principle of REST is that URIs represent nouns (resources), while HTTP verbs represent actions.

Core Best Practices for Resource URIs

• Use Plural Nouns for Collections: Prefer /api/v1/jobs over /api/v1/job.
• Never Put Verbs in Paths: Avoid RPC patterns like /api/v1/getJobs or /api/v1/deleteJob?id=12.
• Model Hierarchical Relationships Naturally: Use nested path segments to represent sub-resources: /api/v1/companies/stripe/jobs.
• Use Hyphenated Lowercase Slugs: Standardize on kebab-case for multi-word paths (e.g., /api/v1/career-advice), avoiding underscores or camelCase.

3. HTTP Methods, Safety, and Idempotency

Understanding the distinction between safe and idempotent operations is critical for building resilient distributed systems that tolerate network timeouts and automated client retries.

┌─────────┬──────────────┬───────────────┬────────────────────────────────────────┐
│ Method  │ Safe (Read)? │ Idempotent?   │ Standard REST Semantics                │
├─────────┼──────────────┼───────────────┼────────────────────────────────────────┤
│ GET     │ YES          │ YES           │ Retrieve resource representation       │
│ HEAD    │ YES          │ YES           │ Retrieve headers without response body │
│ POST    │ NO           │ NO            │ Create subordinate resource or process │
│ PUT     │ NO           │ YES           │ Complete replacement of target resource│
│ PATCH   │ NO           │ CONDITIONAL*  │ Partial modification of target resource│
│ DELETE  │ NO           │ YES           │ Remove target resource                 │
└─────────┴──────────────┴───────────────┴────────────────────────────────────────┘

• Safe Methods: Do not modify server state. Clients can execute them repeatedly without side effects.
• Idempotent Methods: Making $N$ identical requests produces the exact same server state as making 1 request.

The Nuance of PATCH Idempotency

A common misconception is that PATCH is always non-idempotent. In reality, PATCH idempotency depends entirely on the patch format and operation semantics:

1. Idempotent PATCH (JSON Merge Patch - RFC 7396):
   If a client submits:

   PATCH /api/v1/jobs/42
   { "status": "expired", "salaryMax": 185000 }
   

   
   Executing this request five times leaves the resource in the exact same state as executing it once. This is idempotent.
2. Non-Idempotent PATCH (JSON Patch - RFC 6902 / Increment Operations):
   If a client submits:

   PATCH /api/v1/jobs/42
   [
     { "op": "add", "path": "/tags/-", "value": "featured" }
   ]
   

   
   Or if the patch increments a view counter ({ "incrementViews": 1 }), executing the request three times will append the tag three times or increment the counter by 3. This is non-idempotent.

4. Standardized Status Codes and Error Handling (RFC 9457)

Essential Status Codes for Web APIs

• 200 OK: Standard success response for GET, PUT, or PATCH.
• 201 Created: Successfully created a new resource. Must include a Location header containing the URI of the new resource.
• 204 No Content: Operation succeeded, but no payload is returned (standard for DELETE).
• 400 Bad Request: Malformed syntax or invalid request headers.
• 401 Unauthorized: Authentication credentials missing or invalid.
• 403 Forbidden: Authenticated user lacks permission to access the resource.
• 404 Not Found: The target resource does not exist.
• 409 Conflict: The request conflicts with current server state (e.g., duplicate slug or optimistic locking collision).
• 422 Unprocessable Content: The syntax is valid JSON, but fails business domain validation (e.g., salaryMin > salaryMax).
• 429 Too Many Requests: The client exceeded rate limits. Should include a Retry-After header.
• 500 Internal Server Error: Unhandled application failure.

Standardized Error Payloads: RFC 9457 Problem Details

Historically, developers relied on RFC 7807 for error modeling. In 2023, the Internet Engineering Task Force (IETF) officially published RFC 9457 (Problem Details for HTTP APIs), which obsoleted RFC 7807.

RFC 9457 standardizes error reporting using the application/problem+json media type:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.jobscapta.xyz/errors/validation-failed",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The job listing payload failed domain validation checks.",
  "instance": "/api/v1/jobs/postings/req_99214",
  "invalidParams": [
    {
      "name": "salaryMin",
      "reason": "salaryMin must be less than or equal to salaryMax"
    },
    {
      "name": "applyUrl",
      "reason": "applyUrl must be an absolute HTTPS URL"
    }
  ]
}

Adopting RFC 9457 allows frontend and mobile clients to parse error types, titles, and validation parameters predictably across all services.

5. Production Patterns: Pagination, Authentication, and Versioning

A. Pagination: Cursor-Based vs. Offset-Based

When serving large collections, unbounded queries degrade database performance:

• Offset-Based (?page=2&limit=20): Simple to implement using SQL LIMIT and OFFSET. However, it suffers from the "window shift" problem when rows are inserted or deleted while the user is paging, and exhibits $O(N)$ scanning performance at deep offsets.
• Cursor-Based (?cursor=eyJpZCI6NDJ9&limit=20): Uses an indexed sequential column (such as created_at or id) to fetch rows strictly greater or less than the cursor:

  SELECT * FROM jobs WHERE created_at < '2026-10-25T12:00:00Z' ORDER BY created_at DESC LIMIT 20;
  

  Cursor pagination provides $O(\log N)$ performance and guarantees that items are never skipped or duplicated during infinite scrolling.

B. Authentication & Authorization Headers

Standard REST APIs transmit credentials via standard HTTP headers rather than URL query parameters:

• Bearer Tokens (JWT / OAuth2):

  Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...
  

• API Keys for Server-to-Server Integrations:

  X-API-Key: jc_live_9a8f21b7c02e
  

C. API Versioning Strategies

APIs inevitably evolve. The industry recognizes two primary versioning strategies:

1. URI Path Versioning (Recommended for Public APIs):

   https://api.jobscapta.xyz/api/v1/jobs
   https://api.jobscapta.xyz/api/v2/jobs
   

   Explicit, easily debugged in browsers and proxies, and compatible with all client frameworks.
2. Accept Header Content Negotiation:

   Accept: application/vnd.jobscapta.v2+json
   

   Maintains clean canonical URIs, but complicates client-side caching and browser testing.

6. Summary Architectural Checklist

Before publishing a production REST API:

• URIs use plural nouns (/jobs) and avoid RPC action verbs (/getJobs).
• Safe methods (GET, HEAD) never produce destructive side effects.
• PUT provides complete resource replacement, while PATCH handles partial updates.
• PATCH operations distinguish between idempotent field sets and non-idempotent operations.
• Errors conform to RFC 9457 Problem Details (application/problem+json).
• Large collections use cursor-based pagination with indexed keys.
• Rate limits return HTTP 429 with informative Retry-After headers.

To see how backend services coordinate relational and document databases behind these endpoints, read our deep dive on SQL vs. NoSQL Architecture. For high-level system design patterns, explore our System Design Interview Framework.

Primary References and Official Standards

• Fielding, Roy Thomas. (2000). Architectural Styles and the Design of Network-based Software Architectures. Doctoral Dissertation, University of California, Irvine.
• Internet Engineering Task Force (IETF). RFC 9457: Problem Details for HTTP APIs (Obsoleting RFC 7807). rfc-editor.org/rfc/rfc9457
• Internet Engineering Task Force (IETF). RFC 7396: JSON Merge Patch. rfc-editor.org/rfc/rfc7396
• Internet Engineering Task Force (IETF). RFC 9110: HTTP Semantics. rfc-editor.org/rfc/rfc9110