Introduction

Most engineers begin their API journey with CRUD. It teaches how to expose resources, wire endpoints, and push data in and out. But in production systems, APIs do more than shuttle JSON: they enforce contracts, define system boundaries, and dictate performance envelopes. The style and protocol you choose for an API ripple through developer experience, scalability, and even security posture. Senior engineers aren’t just writing routes; they are shaping architecture through API design.

This essay walks through the major API styles – REST, GraphQL, and gRPC – and examines how and when to apply them. Along the way, we’ll look at design principles, trade-offs, and the kind of questions senior developers ask before committing to a style.

REST: The Default Workhorse

REST (Representational State Transfer) has been the dominant style for the past two decades. It maps neatly to HTTP and resource modelling.

Characteristics

• Endpoints model resources using plural nouns (/products, /users/{id})

• Operations mapped to HTTP verbs (GET, POST, PUT, PATCH, DELETE)

• Stateless interactions: each request carries the full context

• Predictable status codes and caching behaviour

Advantages

• Ubiquitous ecosystem: every language and framework supports REST

• Simple mental model: URLs + verbs

• HTTP caching and status codes provide resilience and transparency

Limitations

• Fixed response structures can lead to over-fetching (too much data) or under-fetching (too little, requiring extra calls)

• Complex UIs often need multiple round-trips to stitch together views

• Versioning introduces maintenance overhead (/api/v1, /api/v2)

Use REST when

• Your consumers are browsers, mobile apps, or external partners

• Standardisation, caching, and tooling matter more than flexibility

• Data structures are relatively stable

GraphQL: Flexible Queries, Flexible Clients

GraphQL emerged at Facebook to solve the pain of multiple round-trips and brittle endpoints. It shifts control to the client.

Characteristics

• Single endpoint (often /graphql) for all queries and mutations

• Clients shape responses: request only the fields they need

• Schema-first design: contract defines types, queries, and mutations

• Subscriptions enable realtime updates

Advantages

• Eliminates over-fetching/under-fetching; reduces round-trips

• Ideal for complex UIs where pages need different, nested datasets

• Evolves without explicit versioning; schemas extend incrementally

Limitations

• Error handling differs: responses always return 200 OK with an errors[] array if issues occur

• Requires depth limiting and cost analysis to prevent expensive queries

• Tooling is mature, but ops and caching are less straightforward than REST

Use GraphQL when

• UI is complex, with multiple nested datasets in play

• Bandwidth efficiency matters (mobile-first scenarios)

• You need a single, flexible contract between teams

gRPC: High-Performance RPC

gRPC, built by Google, optimises server-to-server communication. It uses Protocol Buffers (.proto files) to define service contracts and HTTP/2 for transport.

Characteristics

• RPC-style methods (CreateUser, GetOrders) instead of resources

• Strong typing through Protocol Buffers

• Supports streaming: client-stream, server-stream, and bidirectional

• Efficient binary payloads, not verbose JSON

Advantages

• Compact, high-performance wire format

• Natural fit for microservices and internal service meshes

• Bi-directional streaming is powerful for telemetry, chat, or event-driven systems

Limitations

• Browser support is limited; gRPC-Web is a workaround but adds friction

• Requires more upfront tooling and contract management

• Debugging isn’t as straightforward as inspecting raw HTTP/JSON

Use gRPC when

• You’re building microservices that communicate intensively

• Latency and throughput are key performance indicators

• You control both ends of the communication channel

Design Principles Across Styles

Regardless of style, some principles remain universal:

• Consistency: naming, casing, and patterns should never surprise.

• Simplicity: the best API can be understood without documentation.

• Security: authentication, authorisation, rate limits, and input validation are non-negotiable.

• Performance: minimise payloads, use pagination, and reduce round-trips.

These principles anchor APIs in clarity and predictability, no matter what protocol they ride on.

Summary

Choosing between REST, GraphQL, and gRPC isn’t about fashion; it’s about context. REST remains the safe, universal default. GraphQL shines when UI complexity and flexibility dominate. gRPC is unmatched for service-to-service performance.

Senior engineers frame the decision around consumer needs, performance trade-offs, and operational complexity. The real test of an API isn’t how clever it looks in a diagram – it’s whether a new developer can use it without a manual, whether it scales without surprises, and whether it keeps data safe.

In other words: the best API design is invisible. It just works.