{
    "slug": "rest",
    "term": "REST (Representational State Transfer)",
    "category": "architecture",
    "difficulty": "beginner",
    "short": "An architectural style for distributed hypermedia systems using HTTP verbs, stateless interactions, and resource-oriented URLs.",
    "long": "REST (Roy Fielding, 2000) defines six constraints: client-server, stateless, cacheable, uniform interface, layered system, and optional code-on-demand. Practical REST APIs use HTTP verbs semantically (GET retrieves, POST creates, PUT/PATCH updates, DELETE removes), identify resources via URLs, and communicate state via standard status codes (200, 201, 400, 401, 403, 404, 422, 500). True RESTfulness (HATEOAS) is rarely fully implemented — most APIs are REST-like (sometimes called Level 2 of the Richardson Maturity Model). Use consistent status codes and error bodies across all endpoints.",
    "aliases": [
        "RESTful API",
        "Representational State Transfer",
        "REST API"
    ],
    "tags": [
        "architecture",
        "api",
        "http",
        "web"
    ],
    "misconception": "Any HTTP API that uses JSON is RESTful. True REST requires statelessness, a uniform interface, resource-based URLs, and HATEOAS (hypermedia links in responses). Most \"REST\" APIs are actually RPC over HTTP — pragmatically fine, but not architecturally REST.",
    "why_it_matters": "REST constraints (stateless, uniform interface, resource-based URLs) make APIs predictable and cacheable — violating them produces RPC-over-HTTP that loses the benefits of HTTP infrastructure.",
    "common_mistakes": [
        "Verbs in URLs: POST /getUser, GET /createOrder — use nouns and HTTP methods correctly.",
        "Stateful REST: storing session data server-side between requests — each request must be self-contained.",
        "Using GET for state-changing operations — GET must be safe and idempotent; use POST/PUT/PATCH/DELETE.",
        "Returning HTTP 200 for errors — use the appropriate 4xx/5xx status code."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "api_design",
        "graphql",
        "cors_misconfiguration"
    ],
    "prerequisites": [
        "http_status_codes",
        "api_design",
        "hypermedia_api"
    ],
    "refs": [
        "https://restfulapi.net/",
        "https://martinfowler.com/articles/richardsonMaturityModel.html"
    ],
    "bad_code": "// RPC-style URLs with wrong HTTP methods:\nGET  /api/getUser?id=1        // Wrong: verb in URL, should be GET /users/1\nPOST /api/deleteUser          // Wrong: should be DELETE /users/1\nGET  /api/createOrder         // Wrong: GET mutates state — must be POST /orders\nPOST /api/updateUserProfile   // Wrong: should be PATCH /users/1/profile",
    "good_code": "# Resource-oriented URLs + correct HTTP verbs\nGET    /users          # list\nPOST   /users          # create\nGET    /users/{id}     # read\nPUT    /users/{id}     # full replace\nPATCH  /users/{id}     # partial update\nDELETE /users/{id}     # delete\n\n# PHP: return appropriate status codes\nreturn response()->json($user, 201);   // Created\nreturn response()->json(null, 204);    // No Content (DELETE)\nreturn response()->json($errors, 422); // Unprocessable Entity",
    "quick_fix": "REST is a set of constraints, not a protocol — use HTTP verbs correctly (GET safe/idempotent, POST create, PUT/PATCH update, DELETE remove), return appropriate status codes, and keep resources as nouns in URLs",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/rest",
        "html_url": "https://codeclaritylab.com/glossary/rest",
        "json_url": "https://codeclaritylab.com/glossary/rest.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[REST (Representational State Transfer)](https://codeclaritylab.com/glossary/rest) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/rest"
            }
        }
    }
}