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

Original Article ↗ Hacker News Discussion ↗

gRPC, REST/“REST-ish” JSON over HTTP, and OpenAPI are contrasted as competing approaches to API design, with developers sharply divided over their practicality and ergonomics. Many praise gRPC’s strong typing, code generation, and streaming for internal service-to-service calls, but criticize its tooling quality, browser incompatibility, and operational complexity compared to simple HTTP+JSON. Others argue that most real-world APIs are not “true” REST as defined by Roy Fielding, and that in practice OpenAPI-described JSON APIs hit a better balance for public and frontend-facing use, while gRPC makes more sense in tightly controlled backends and larger organizations.

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).