Choosing the Right API Style
⚖️ Choosing the Right API Style
The Full Lineup, One Line Each
| Style | One-Liner | Best For |
|---|---|---|
| REST | Resource-based request/response over HTTP | General-purpose public and web APIs |
| SOAP | Formal XML contracts, WS-* standards | Enterprise/banking/government systems needing strict guarantees |
| RPC / gRPC | Call a specific function directly | High-performance internal microservices |
| GraphQL | Client asks for the exact shape of data it wants | Complex UIs assembling data from many sources |
| WebSockets | A persistent, two-way connection | Real-time bidirectional communication |
| Webhooks | The server calls you when something happens | Event notification, avoiding polling |
Question 1: Who's the Client — the Public, or You?
A broad, external, uncoordinated audience with variable needs generally points toward REST or GraphQL — both are widely understood and tooling-friendly. Tightly coupled internal services you also control point toward gRPC — its performance and strict typing pay off precisely because you control both ends and can regenerate client code whenever the contract changes. Formal enterprise partners requiring guaranteed contracts and transactional integrity point toward SOAP.
Question 2: Is It Actually Request/Response, or Something Else?
If the communication is genuinely two-way and continuous — a chat app, a live dashboard, a multiplayer game — that's WebSockets territory, already covered in its own full course. If the real need is "notify me later, don't make me keep asking," that's Webhooks. If it's a client asking a question and getting one answer back, the request/response styles (REST, SOAP, RPC/gRPC, GraphQL) are the right family to be choosing among at all.
Question 3: How Complex Are the Client's Data Needs?
If clients mostly need simple, fixed-shape access to a resource, plain REST is enough — and simpler to build and reason about than the alternative. If a client needs to assemble deeply nested, varying combinations of data across many different screens (recall the GraphQL course's over-fetching/under-fetching problem), that's exactly the complexity GraphQL earns its own extra weight by solving.
Question 4: What Guarantees Do You Actually Need?
If you need enforced, machine-validated contracts plus built-in transactional and message-level security guarantees, that's SOAP's specific strength (Chapter 5). If you need raw performance and binary efficiency for service-to-service calls, that's gRPC. Otherwise, REST's informal contract — optionally documented with OpenAPI, as covered in express2-7 — is enough for the vast majority of APIs.
A Worked Example
Consider building the backend for a public social media platform:
The Main API
Broad external audience (Q1 → REST or GraphQL), and mobile screens assembling posts + comments + likes + author info in different combinations per screen (Q3 → the complexity GraphQL is built for). Conclusion: GraphQL for the main data API.
Live Notifications
Genuinely continuous, two-way communication the instant a new like or comment arrives (Q2 → not request/response at all). Conclusion: WebSockets, already covered in its own course.
Third-Party Integrations
A partner app wants to know whenever a user posts something, without polling constantly (Q2 → event notification, not a live connection). Conclusion: Webhooks for outbound event notifications to partners.
Notice the answer wasn't "one style for the whole platform" — real systems very often combine several API styles, each handling the specific part of the problem it's actually good at.
💻 Coding Challenges
Challenge 1: A Public Weather API
You're building a public developer-facing weather API expecting millions of simple, mostly-uniform requests (get the forecast for a location). Which style fits, and why?
Goal: Practice recognizing when the SIMPLEST fitting style is the right choice, not the most sophisticated one.
Challenge 2: Two Internal, Latency-Sensitive Microservices
An order service and an inventory service, both owned by your own team, need extremely low-latency communication with each other. Which style fits, and why?
Goal: Practice applying Question 1 and Question 4 together — control over both ends, plus a genuine performance requirement.
Challenge 3: Design a Multi-Style System
An e-commerce platform needs: (a) a public product-browsing API, (b) live order-tracking updates for a customer watching their delivery, and (c) letting partner logistics companies know the instant stock runs low. Identify which API style fits each of the three needs.
Goal: Practice the worked example's lesson — that one real system often needs more than one API style.
It's tempting, once you've committed to building a REST API, to make it handle EVERYTHING — including needs it's genuinely bad at, like simulating "real-time" updates by having the client poll a REST endpoint every second. That approach technically works, but it reproduces exactly the wasteful, laggy pattern Chapter 7 described polling as a problem in the first place — when a WebSocket connection or a webhook would solve the same need properly. The worked example above is the real lesson: don't default to whichever style you already have running: ask, per feature, which style that specific piece of functionality actually needs.
🎯 What's Next
The final chapter, Capstone: Designing an API for a Real Scenario, puts everything from this course into practice — given a real scenario, choosing and justifying an API style and sketching out its actual design.