Understanding gRPC, OpenAPI and REST and when to use them in API design (2020)

Original Article ↗ Hacker News Discussion ↗

Definitions and terminology

  • Strong disagreement with the article’s framing that REST is “least used” and distinct from OpenAPI; many argue OpenAPI is just a way to describe HTTP APIs, including REST-ish ones.
  • Long subthread on “true REST” vs common “REST-like” JSON/HTTP:
    • “True REST” = HATEOAS, clients discover URLs via hypermedia and don’t construct them.
    • Most real-world “REST APIs” are actually JSON-over-HTTP / RPC over HTTP, often called “RESTful” or “RESTish.”
  • Some feel insisting on strict Fielding-style REST is pedantic; others argue changing the meaning causes confusion.

gRPC: strengths and intended use

  • Advocates like it for internal, service-to-service calls: strong schemas, code generation, type safety, versioning/deprecation semantics, and efficient binary encoding.
  • Considered a good fit for large orgs, microservice meshes, language polyglot backends, and streaming (especially server or bidi streams).
  • Some report smooth use at mid-sized companies, or at big tech, when infra teams provide unified tooling (service discovery, routing, reflection, “curl for RPC”).
  • Protobuf schemas seen as concise and good for cross-language data modeling; OpenAPI-like specs can be generated from gRPC.

gRPC: drawbacks and pain points

  • Many report poor developer experience: heavy tooling, awkward codegen (esp. Java, Python, Node), confusing timeouts/retries, and difficult debugging of binary HTTP/2 traffic.
  • Browser and JS support is weak; requires proxies / gRPC-Web / ConnectRPC, and often still feels clumsy.
  • Middleboxes and incomplete HTTP/2 implementations can break it; some saw flaky behavior over the public internet.
  • Proto evolution, optional fields, and loose validation can lead to subtle bugs and security concerns; versioning is hard in practice.
  • Critiques of protobuf itself: non-stream-friendly design, tricky framing, default values, and ambiguity when mismatched schemas are used.

REST/JSON & OpenAPI: pros and cons

  • JSON-over-HTTP is praised for simplicity, human readability, easy curl/Postman use, and browser-friendliness; ideal for public APIs and front-end consumption.
  • Downsides: loose typing, fragmented semantics across URL/query/body/headers, inconsistent REST “purity,” and very mixed OpenAPI tooling quality.
  • Codegen from OpenAPI can be powerful but often clunky; many teams only use it for docs, not stubs.

Streaming, performance, and alternatives

  • Some say gRPC’s performance benefits are overhyped for typical workloads; compression + JSON is usually “good enough.”
  • Streaming is acknowledged as a real gRPC strength, but bidi streams complicate retries, load balancing, and fault tolerance.
  • GraphQL surfaces as an alternative: great for flexible data fetching, but can create opaque, hard-to-optimize DB queries and load issues at scale.

Pragmatic guidance and rules of thumb

  • Common heuristics from the thread:
    • Public or browser-facing APIs → JSON/HTTP + (good) OpenAPI, maybe GraphQL if you need flexible queries.
    • Internal microservices at scale, strong infra support, monorepo/shared tooling → gRPC can shine.
    • Small teams / simple CRUD / heterogeneous clients → avoid gRPC; stick to JSON/HTTP (possibly with schema and codegen).