REST is the de facto standard for web APIs, but it is neither the only tool nor always the best one. In recent years alternatives have matured that attack very specific limitations: GraphQL was born from the problem of requesting tailored data from mobile; gRPC, from the need for high-performance internal communication; webhooks, from HTTP's inability to let the server notify the client. This lesson closes the module by drawing the complete map of integration styles, with examples applied to Aroma Store, so that you can choose with judgement and — most importantly — understand that these approaches do not compete: they coexist within the same company, each in its own place.

1. Why a single style is not enough
2. GraphQL: the client decides which fields it wants
3. What problems GraphQL solves and which ones it introduces
4. gRPC: a strong contract and high performance between services
5. Event-driven communication: webhooks
6. Queues, streaming and real time: SSE and WebSockets
7. Comparison table of the four approaches
8. Honest decision criteria
9. Aroma Store's final architecture

Aroma Store's communication needs are not homogeneous. Compare these four cases:

Each mismatch has a specific answer. Seeing them together gives you judgement; using them all at once for no reason gives you an ungovernable architecture.

GraphQL is a query language for APIs, created at Facebook in 2012 and published in 2015. Its three fundamental decisions:

1. A typed schema defines all the available data and its relationships. It is the contract, and it is mandatory.
2. A single URL (typically /graphql), which you POST to.
3. The client writes the query: it asks for exactly the fields it needs, not one more.

The ! sign means "cannot be null". The schema is documentation, validation and contract all at once: tools read it and offer autocompletion as you write queries.

For its catalogue screen, the mobile app needs only the name, the price and the average rating. It asks for it like this:

And it receives exactly that, with the same shape as the query:

Over HTTP, the actual request is a POST:

Achieving the same thing with the Aroma Store REST API would take several calls:

Eleven requests against one, and the first one downloads origin, roast, stock and tastingNotes that the screen does not use. That is exactly GraphQL's argument.

It is worth qualifying that, in fairness: REST has partial answers to this problem — expansion parameters (?include=reviews), field selection (?fields=name,priceEuros) and aggregate endpoints designed for one specific screen. The thing is that in REST these are ad hoc conventions that each API solves in its own way, whereas in GraphQL it is the model itself.

Note something you can already recognise: in Richardson's terms, GraphQL is a level 0 — one endpoint, everything by POST, the operation inside the body. The difference from the swamp of POX is that here the choice is deliberate and comes with a typed contract, introspection and a tooling ecosystem that compensates for what is lost.

gRPC (Google, 2015) is modern RPC. Its pillars:

• Protocol Buffers (protobuf): a compact, typed binary format for serialising messages.
• HTTP/2 as transport, with multiplexing and compressed headers.
• A contract in a .proto file from which client and server code is generated in more than ten languages.
• Four communication modes, including streaming in both directions.

The numbers (= 1, = 2) are not values: they are the field tags that take the place of names in the binary format. That is why protobuf is so compact — it does not send the field names — and why those numbers must never be changed once published: they are the real contract.

From Node.js, consuming it looks like a function call:

In favour: messages far smaller than JSON, faster serialisation, a strong contract with code generation, native streaming, excellent for high-volume internal traffic and for communication between services written in different languages.

Against: it is not directly consumable from a browser (it needs a gateway such as gRPC-Web), binary messages cannot be read with your eyes or debugged with curl, it does not make use of HTTP caching, and the tooling is poorer outside prepared environments. It is not a good candidate for a public API.

Everything we have seen so far shares one limitation: the client asks and the server answers. So how does Aroma Store notify SwiftShip that an order has been paid and is ready for collection?

The naive option is polling: SwiftShip checks every minute.

With one order every half hour and one query per minute, 98% of the requests are useless: they burn resources on both sides and the notification still arrives up to a minute late.

A webhook reverses the direction: the consumer registers a URL of its own, and the provider POSTs to it when something happens. It is, literally, "an API in reverse": now Aroma Store is the HTTP client and SwiftShip the server.

Sending the event:

Four design decisions you will see in every serious webhook and that are worth internalising right away:

1. Cryptographic signature (Aroma-Signature): the receiver recalculates an HMAC of the body with a shared secret and checks that it matches. Without this, anyone who knows the URL can invent events.
2. Event identifier (Aroma-Event-Id): it lets the receiver detect duplicates. Webhooks guarantee "at least once" delivery, so the receiver must be idempotent.
3. Retries with increasing backoff: if the receiver does not respond with a 2xx, the sender retries at ever longer intervals over hours, and raises an alert if it eventually gives up.
4. Namespaced event type (order.paid, order.shipped, review.published): it allows selective subscription and the addition of new events without breaking anything.

Webhooks do not replace the REST API: they complement it. The usual approach is for the event to carry just enough and for the receiver to call the API afterwards to obtain the complete, up-to-date detail.

Let's complete the map with three mechanisms that will turn up in your professional life:

• Message queues and streaming (RabbitMQ, Kafka, SQS): the internal equivalent of webhooks. The sender publishes an event to a broker and interested parties consume it at their own pace. They provide persistence, retries, ordering and total decoupling. Aroma Store would use them so that the invoicing, loyalty and analytics services can react to order.paid without the orders service even knowing they exist.
• Server-Sent Events (SSE): a long-lived HTTP channel over which the server sends messages to the client. Unidirectional, simple, over ordinary HTTP, with automatic reconnection built into the browser. Ideal for the Aroma Store internal panel showing orders as they come in.
• WebSockets: a persistent bidirectional channel over a connection upgraded from HTTP. Necessary when both ends talk continuously: a customer service chat, for example.

A useful rule: if the user has to find out about something without asking for it, you need one of these four; no REST, GraphQL or unary gRPC API solves it on its own.

Concrete questions, in order of importance:

1. Who consumes the API? If it is third parties you do not control, REST. The lowest barrier to entry wins almost every time; a public API in gRPC would be a mistake.
2. Is the data cacheable? If the catalogue is queried thousands of times and changes little, REST's free HTTP caching is a weighty argument that is hard to match.
3. Do your clients need highly variable combinations of data? If you have many different screens over the same model and genuinely suffer from over/under-fetching, GraphQL delivers real value.
4. Is it internal communication with high volume and critical latency? gRPC. You control both ends, so the contract coupling does not hurt and the performance is noticeable.
5. Is the server the sender? Webhooks outwards, queues inwards. There is no debate: client-server HTTP does not cover this case.
6. What is the size and experience of your team? An excellent architecture nobody knows how to operate is worse than a good one everybody understands. Badly operated GraphQL is an inexhaustible source of performance incidents.

Three warnings, from the industry's accumulated experience:

• Do not adopt GraphQL just to avoid two requests. With HTTP/2 several small requests are cheap, and REST supports expansion parameters and field selection.
• Do not use gRPC facing outwards unless your consumers are technical teams capable of integrating it.
• Do not implement webhooks without signatures, retries and idempotency. A badly built webhook produces duplicated orders or lost events, and both show up in the accounts.

With the whole map on the table, here is the team's decision, and it is the one we will follow for the rest of the course:

And an equally important decision: GraphQL, for now, no. The team has assessed it and concluded that its screens are few and stable, that the catalogue cache is an asset it does not want to lose and that the team is small. It is a revisable decision, taken with arguments and written down. That is what designing looks like; the opposite is following fashion.

• Choosing by fashion rather than by problem. Always ask what specific limitation you are suffering from today. If you cannot name it, do not change technology.
• Believing that GraphQL replaces REST. They are complementary. Many companies expose GraphQL for their own clients and REST for third parties, over the same backend.
• Forgetting that GraphQL loses HTTP caching. If your traffic is mostly reads of slowly changing data, that loss can cost more than you save in requests.
• Using gRPC in the browser without a gateway. It does not work directly: you need gRPC-Web and a proxy that translates.
• Changing the field numbers in a .proto. It breaks binary compatibility silently and in a way that is hard to diagnose. The numbers are the contract.
• Treating a webhook as a guaranteed, single delivery. It arrives at least once, and sometimes more. Without idempotency in the receiver, you will get duplicates.
• Putting complete, sensitive data in the webhook body. Send the minimum and let the receiver query the API if it needs more: the event may arrive late and with data that is already out of date.
• Tip: keep a simple rule — REST outwards, gRPC inwards, events for anything asynchronous — and deviate from it only with a reason you can write down in two lines.

For each Aroma Store need, choose between REST, GraphQL, gRPC, a webhook or SSE, and justify it with two arguments:

1. An external price comparison site wants to query the catalogue every hour.
2. The orders service checks stock 800 times a second before confirming purchases.
3. Aroma Mobile's "my account" screen shows the customer's details, their last three orders, the shipping status of each one and their reviews.
4. The roasting supplier must find out as soon as a coffee's stock drops below 20 units.
5. The warehouse panel shows orders as they come in, without reloading.

Design the order.shipped webhook that Aroma Store will send to any customer who requests it. Specify: the event's JSON body, the necessary headers, what the receiver must respond, what the sender will do if it does not respond and which security measures you include.

The coffee detail screen in Aroma Mobile needs: the name, price, stock, the last five reviews (author and rating) and the roaster's name.

1. How many REST requests would a naive design take?
2. Write the equivalent GraphQL query.
3. Propose two solutions within REST that reduce the number of requests without adopting GraphQL.
4. What is lost in each case?

Solution 1

1. REST. It is an unknown third party that must be able to integrate without friction, and the catalogue is public, cacheable content: Cache-Control means many of those queries never even reach the server.
2. gRPC. It is internal traffic with both ends under your control, where the binary format and HTTP/2 reduce latency and CPU compared with JSON; in addition the .proto contract prevents type errors on a critical path.
3. GraphQL would be the ideal candidate, as it combines four data sources into a single query, avoiding the N+1 request problem. That said, if it is the only screen with that problem, the pragmatic answer is an aggregate REST endpoint (GET /v1/customers/cus_842/summary): it solves the case without introducing a whole technology.
4. Webhook. The sender is Aroma Store and the receiver is an external company; constant polling would be wasteful and would add delay to the notification.
5. SSE. It is a unidirectional flow from the server to the browser, it works over ordinary HTTP and it reconnects on its own. A WebSocket would be needlessly complex because the panel sends nothing back.

Solution 2

Event body:

Headers:

What the receiver must respond: a 2xx (ideally 200 OK or 204 No Content) as soon as possible, before processing the event. The rule is accept, enqueue and process asynchronously: if you take a long time to respond because you are doing heavy work, the sender may treat it as a failure and retry, generating duplicates.

If it does not respond: retries with increasing backoff (for example, after 30 s, 2 min, 10 min, 1 h, 6 h and 24 h), a log of every attempt available to the consumer, an email alert after several failures and deactivation of the endpoint after a number of consecutive failures.

Security:

• HMAC-SHA256 signature of the body with a shared secret, which the receiver verifies before processing anything.
• A timestamp in the signature to reject old resends (replay attacks).
• HTTPS mandatory on the destination URL.
• An event identifier so the receiver can discard duplicates.
• Minimal data: no payment data and no unnecessary personal data; if more is needed, let the receiver query the API with authentication.

Solution 3

1. REST requests with a naive design: three.

2. GraphQL query: one.

3. Two solutions within REST:

• An expansion parameter: GET /v1/coffees/cof_001?include=reviews,roaster, which returns the related resources embedded in the same response. A single request, and it is still a cacheable GET.
• A screen-oriented aggregate resource: GET /v1/coffees/cof_001/detail, designed specifically for that view. Simple and very efficient.

4. What is lost in each case:

• With GraphQL: HTTP caching (everything is a POST to /graphql), meaningful status codes and the ability to try the call from the browser; on top of that, query cost has to be controlled.
• With the expansion parameter: the cache fragments (each combination of include is a separate entry) and the server gets more complicated; if it is overused, you end up reimplementing GraphQL by hand, and worse.
• With the aggregate resource: the API becomes coupled to one specific screen. If every new view adds its own endpoint, the API fills up with bespoke resources that are hard to maintain and to document.

There is no free option: all three are conscious trade-offs, and choosing well means knowing which one hurts least in your context.

You now have the complete map of integration styles. REST stands out for its simplicity, its universality and the caching it inherits from HTTP, and it is the natural choice when the consumer could be anyone. GraphQL solves over-fetching and under-fetching by giving the client control over the fields, in exchange for losing HTTP caching and having to govern query cost. gRPC brings a strong contract, a binary format and streaming, and shines between internal services where you control both ends. And webhooks, together with queues, SSE and WebSockets, cover the gap that no request-response model can cover: letting the server take the initiative. The practical conclusion is that they do not compete: Aroma Store will use REST outwards, gRPC inwards and webhooks for its integrations, and it has left GraphQL out for reasons that are written down and revisable.

With this we close module 1. You know what an API is and who it is designed for, where today's ecosystem comes from, how HTTP works underneath, what the six REST constraints consist of, how to measure an API's maturity and what alternatives exist. It is time to move from understanding to building. In module 2, RESTful API Design, we will start designing the Aroma Store API piece by piece: its design principles, its resources and URIs, the precise use of each HTTP method and each status code, content negotiation, filtering and pagination, versioning and documentation. That is the moment when the ideas in this module turn into concrete decisions about a real contract.