REST and GraphQL are the two dominant API design patterns in web development. The choice between them affects API usability, development velocity, and maintenance complexity. Here is an honest framework.
What REST Is
Representational State Transfer (REST) is an architectural style for APIs where resources are represented as URLs (endpoints), and operations on those resources use HTTP verbs (GET, POST, PUT, DELETE, PATCH). A REST API for a blog might have: GET /articles (list articles), GET /articles/:id (single article), POST /articles (create), PUT /articles/:id (update), DELETE /articles/:id (delete). REST is stateless, uses HTTP caching naturally, and is human-readable. The limitation: a client that needs a specific combination of fields across multiple resources makes multiple requests and receives more data than needed (overfetching) or less (underfetching).
What GraphQL Is
GraphQL (Facebook, 2015) is a query language for APIs where the client specifies exactly what data it needs in a single request. A GraphQL query might ask for: user name, their last 3 posts with just title and date, and each post’s comment count — all in one round trip. The server returns exactly that structure. Benefits: no overfetching, no underfetching, strong typing through a schema, automatic API documentation (the schema is the documentation), and reduced need for API versioning (you add fields; old clients still work). The costs: more complex server implementation, query depth attacks (a malicious client can write queries that hit the database exponentially), and caching is harder (POST requests to a single endpoint don’t benefit from HTTP caching without extra tooling).
When to Choose REST
Choose REST for: public APIs where you cannot control the clients, simple CRUD applications where the REST model maps naturally to operations, systems where HTTP caching is important (CDN caching, public read-heavy APIs), teams that are unfamiliar with GraphQL, and microservices where inter-service calls are well-defined and relatively stable. REST is also easier to test and debug — standard HTTP tools (curl, browser) work without modification.
When to Choose GraphQL
Choose GraphQL for: applications with multiple client types that need different data shapes (web, mobile, TV app all hitting the same API), data-heavy applications where fetching efficiency matters, product-focused teams where frontend developers want to move fast without waiting for backend endpoint changes, and when you already have a well-defined data model that maps cleanly to a schema. GitHub, Shopify, Twitter, and most large consumer tech companies have moved their public APIs to GraphQL for partner integrations. The most common mistake with GraphQL: using it for a simple internal CRUD API where REST would have been simpler and sufficient.
