{
    "slug": "graphql_vs_rest",
    "term": "GraphQL vs REST vs gRPC",
    "category": "api_design",
    "difficulty": "intermediate",
    "short": "REST for public APIs and resource-oriented design, GraphQL for flexible client-driven queries, gRPC for high-performance internal service communication.",
    "long": "REST: resource-based (nouns in URLs), standard HTTP methods, cacheable with CDN, well understood — best for public APIs and simple CRUD. GraphQL: client specifies exact fields needed, single endpoint, eliminates over/under-fetching, but complex caching and N+1 risks — best for frontend-driven APIs with diverse client needs. gRPC: Protocol Buffers binary serialisation, HTTP/2, bidirectional streaming, strongly typed contracts, 5-10x faster than JSON REST — best for internal microservice communication where performance matters.",
    "aliases": [
        "REST vs GraphQL",
        "gRPC vs REST",
        "API protocol comparison"
    ],
    "tags": [
        "api-design",
        "architecture",
        "graphql",
        "grpc"
    ],
    "misconception": "GraphQL is always better than REST because it avoids over-fetching — GraphQL adds N+1 risk, complex caching requirements, and operational overhead; for simple resource APIs, REST with sparse fieldsets is cleaner.",
    "why_it_matters": "Choosing the wrong API protocol forces expensive migrations — a public REST API chosen for a mobile app with highly variable data requirements causes persistent over-fetching; GraphQL would have been better.",
    "common_mistakes": [
        "GraphQL for internal service communication — gRPC is faster and better typed.",
        "REST for APIs with deeply variable client data needs — GraphQL handles this naturally.",
        "No DataLoader with GraphQL — N+1 problem makes GraphQL slower than REST without it.",
        "gRPC for browser-facing APIs — gRPC requires grpc-web proxy for browser clients."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "graphql",
        "rest_constraints",
        "grpc",
        "api_gateway"
    ],
    "prerequisites": [
        "rest_constraints",
        "graphql",
        "api_design"
    ],
    "refs": [
        "https://www.apollographql.com/docs/"
    ],
    "bad_code": "// REST for mobile app — persistent over-fetching:\nGET /api/users/42\n// Returns: all 25 fields\n// Mobile needs: name, avatar (2 fields)\n// 23 fields wasted on every request",
    "good_code": "// Right tool for the job:\n\n// Public REST API — simple, cacheable, well-understood:\nGET /api/products/42          → product data (CDN cacheable)\n\n// GraphQL for mobile/web with varied needs:\nquery { user(id:42) { name avatar } }  → exactly 2 fields\n\n// gRPC for internal PHP microservices:\n// payment.proto: rpc Charge(ChargeRequest) returns (ChargeResponse)\n// Generated PHP client + binary protocol\n// 5x faster than JSON REST for high-frequency calls",
    "quick_fix": "Use REST for simple CRUD with well-defined resources; use GraphQL when clients have highly varying data needs, multiple clients need different shapes, or you want to reduce over/under-fetching",
    "severity": "info",
    "effort": "medium",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/graphql_vs_rest",
        "html_url": "https://codeclaritylab.com/glossary/graphql_vs_rest",
        "json_url": "https://codeclaritylab.com/glossary/graphql_vs_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": "[GraphQL vs REST vs gRPC](https://codeclaritylab.com/glossary/graphql_vs_rest) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/graphql_vs_rest"
            }
        }
    }
}