GraphQL is an API query approach in which the client describes the response shape it needs, allowing related data to arrive in one response without unused fields. section 5.3.3
The performance problem is request coordination. Resource-oriented REST endpoints can force clients to make several sequential calls or accept oversized responses. GraphQL consolidates related data and reduces unnecessary bytes, which matters most on slower connections and in high-latency flows. section 5.3 section 5.3.3
Use the approach comparison to frame the main trade-offs:
- Choose GraphQL when diverse clients or mobile applications need different combinations of related data. section 5.3.3
- Expect medium-sized JSON payloads and native browser support, but plan custom caching rather than relying directly on HTTP caching. section 5.3.3
- Treat the learning curve as medium and debugging as good, while recognizing that GraphQL trades REST simplicity for query flexibility. section 5.3.3
GitHub pull-request display
A pull-request screen originally required separate calls for the pull request, commits, comments, and reviews. A unified GraphQL query fetched these related resources together, reducing four calls to one and allowing clients to request only the fields they used. section 5.3.3
Table 5.2 API approach comparison
|
|
REST
|
GraphQL
|
gRPC
|
|
Best for
|
Public APIs, cacheable resources
|
Diverse client needs, mobile apps
|
Internal services, high throughput
|
|
Payload size
|
Medium (JSON)
|
Medium (JSON)
|
Small (binary)
|
|
Caching
|
HTTP caching works naturally
|
Requires custom solutions
|
Requires custom solutions
|
|
Browser support
|
Native
|
Native
|
Requires proxy
|
|
Learning curve
|
Low
|
Medium
|
Medium-high
|
|
Debugging
|
Excellent
|
Good
|
Requires tooling
|
|
Round trips
|
One per resource
|
One for complex queries
|
One (streaming supported)
|
Compare GraphQL with REST and gRPC across client fit, payloads, caching, browser support, learning curve, debugging, and round trips. section 5.3.3







