APIs from zero

Kinds of APIs

REST, GraphQL, WebSockets, server-sent events, SOAP and gRPC — how each works, what it's good at, and what changes when you test it.

Not all APIs are shaped the same way. You'll meet a few styles; the ideas from the earlier lessons — requests, status codes, JSON, signing in — carry over to all of them.

REST: resources and methods

What the earlier lessons described is REST, by far the most common style: resources at addresses (/orders/A-1001), methods that say what to do (GET, POST…), status codes, and usually JSON. One request, one response.

  • Good at: simple, predictable, easy to cache and to test. Every tool understands it.
  • Watch out for: getting too much (the whole order when you wanted its status) or too little (an order, then one more request per item — the "N+1" pattern that slows apps down).

Strictly, REST has more rules than "JSON over HTTP"; in practice people call most JSON-over-HTTP APIs REST, and so will these lessons.

GraphQL: ask for exactly what you need

A GraphQL API has one address (often /graphql) and you send a query saying exactly which fields you want:

query {
  order(id: "A-1001") {
    status
    items { sku quantity }
  }
}

and the answer has exactly that shape:

{ "data": { "order": { "status": "paid", "items": [ { "sku": "LAMP-1", "quantity": 1 } ] } } }

Changes are mutations (mutation { cancelOrder(id: "A-1001") { status } }). The API publishes a schema — every type and field — which tools can load to help you write queries.

  • Good at: apps that need different slices of the same data; one round trip instead of many.
  • Testing it: the status is usually 200 even when something failed — errors come in an errors list in the body. A GraphQL test must check that errors is absent, not just the status. Load tests must also send realistic queries: one deep query can cost the server far more than a hundred simple ones.

WebSockets: a conversation

A WebSocket starts as an HTTP request and then stays open: both sides can send messages at any time, for as long as the connection lasts. Addresses start with ws:// or wss:// (encrypted).

→ connect   wss://chat.example.com/rooms/42
← { "type": "welcome", "users": 3 }
→ { "type": "message", "text": "hello" }
← { "type": "message", "from": "Ann", "text": "hi!" }
  • Good at: chat, live dashboards, trading, multiplayer games, collaboration — anything where the server must tell you things without being asked.
  • Testing it: there are no status codes per message. You test the conversation: does the welcome arrive, does a message come back, does it close cleanly? When a connection closes, a close code says why (1000 normal, 1006 lost, 1008 policy — often auth).

Server-sent events (SSE): a stream of updates

SSE is simpler: an ordinary GET whose answer never quite ends. The server keeps sending events, one after another:

event: tick
id: 1
data: {"price": 44.3}

event: tick
id: 2
data: {"price": 43.9}

It's one-way (server to you), uses plain HTTP, and reconnects easily. It's how many notification feeds, progress bars and AI chat answers that appear word by word work.

SOAP: the older, stricter style

SOAP APIs send XML documents in a fixed "envelope", described by a WSDL file. You'll find them in banks, insurance, government and older enterprise systems. To test one: POST the XML envelope to its address with Content-Type: text/xml (and often a SOAPAction header) — the ideas are the same, the format is wordier.

gRPC: fast, binary, between services

gRPC sends compact binary messages described by .proto files, over HTTP/2. It's popular between services inside a company because it's fast and strictly typed. You need tools that read the .proto file; you can't just type JSON.

Which one am I looking at?

You seeIt's probably
Many paths, GET/POST/…, JSONREST
One /graphql path, query { … } in the bodyGraphQL
An address starting ws:// or wss://WebSocket
Content-Type: text/event-stream in the answerServer-sent events
XML envelopes, a .wsdl fileSOAP
.proto files, HTTP/2, binarygRPC

Key takeaways

  • REST — resources, methods, status codes, JSON; the default.
  • GraphQL — one address, ask for exactly the fields you need; errors arrive with status 200, so check the body.
  • WebSockets are two-way conversations; SSE is a one-way stream of events; SOAP is XML envelopes; gRPC is binary messages between services.

In the app: GraphQL · WebSockets and event streams

Next: What API testing is

A question these lessons don’t answer? Write to support@apitestcenter.com — we add lessons for the questions people ask.