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
errorslist in the body. A GraphQL test must check thaterrorsis 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 see | It's probably |
|---|---|
| Many paths, GET/POST/…, JSON | REST |
One /graphql path, query { … } in the body | GraphQL |
An address starting ws:// or wss:// | WebSocket |
Content-Type: text/event-stream in the answer | Server-sent events |
XML envelopes, a .wsdl file | SOAP |
.proto files, HTTP/2, binary | gRPC |
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