Beyond REST: GraphQL, WebSockets and webhooks

Where REST is not enough

In REST, the server decides what each URL returns. Sometimes it sends too much (over-fetching: the whole restaurant with its menu when you only wanted the name). Sometimes too little (under-fetching: you need three requests to build one screen). And REST only answers when asked, so it cannot push news to you the moment it happens.

GraphQL: ask for exactly what you need

GraphQL is a query language for APIs. There is usually one endpoint (POST /graphql). A schema describes every type and field the API offers. The app sends a query that names the fields it wants, and the reply has the same shape. A resolver is the server function that fetches the data for one field.

type Restaurant {
  id: ID!
  name: String!
  city: String!
  rating: Float
  menu: [Dish!]!
}

type Dish {
  name: String!
  price: Int!
}

type Query {
  restaurant(id: ID!): Restaurant
}

# The query the app sends
query {
  restaurant(id: "42") {
    name
    city
  }
}

# The reply: only the fields that were asked for
{ "data": { "restaurant": { "name": "Sharma Dhaba", "city": "Pune" } } }

GraphQL has costs too. HTTP caching is harder because everything goes to one URL. A client can send a very deep, expensive query, so servers limit query depth and cost. Use it when many different screens or apps need different slices of the same data.

WebSockets and Server-Sent Events

A WebSocket starts as a normal HTTP request with an Upgrade header, then turns into a two-way connection that stays open. Both sides can send messages at any time. It suits chat, a delivery partner moving on the map, and multiplayer games. Server-Sent Events (SSE) keep a plain HTTP response open and let only the server send. The browser reads it with EventSource and reconnects by itself. SSE suits a live cricket score, notifications and streaming AI text.

// WebSocket: two-way
const socket = new WebSocket('wss://example.com/live');
socket.addEventListener('open', () => {
  socket.send(JSON.stringify({ type: 'subscribe', matchId: 123 }));
});
socket.addEventListener('message', (event) => {
  const update = JSON.parse(event.data);
  console.log(update.score); // for example "IND 182/4 (18.2)"
});

// Server-Sent Events: server to browser only
const feed = new EventSource('/api/matches/123/stream');
feed.onmessage = (event) => console.log(JSON.parse(event.data));

Webhooks: the other server calls you

1. You give the payment gateway a URL on your server, for example https://yourshop.in/api/webhooks/payments, and it gives you a webhook secret.
2. When a payment succeeds, the gateway sends a POST request with JSON to that URL.
3. It adds a signature header: an HMAC-SHA256 of the raw request body, made with the shared secret. HMAC is a code that only someone with the secret can produce.
4. Your server computes the same HMAC over the raw body and compares. If it does not match, reply 400 and stop.
5. Reply 200 quickly (within a few seconds). Do slow work, like emails and invoices, in a background job.
6. If your server is slow or down, the gateway retries, so the same event can arrive twice. Save each event id and skip ids you have already processed. This makes the handler idempotent: running it twice has the same effect as once.

gRPC is another style, used mostly between services inside one company. You describe methods and messages in a .proto file, a tool generates client and server code, and data travels in a compact binary format over HTTP/2. It is fast and strictly typed, but browsers cannot call it directly without a helper, so public APIs still use REST or GraphQL.

When to use which