Not Every API Is REST: Reading SOAP and GraphQL Without Panic
You learn APIs with REST: call a URL, get JSON back. Then your first enterprise customer wants their payroll system connected, and the docs start with a .wsdl file. Or a newer tool gives you one URL and says "send a query". Here is how not to freeze.
The quick difference
- REST: one URL for each kind of thing, like /employees/42. The HTTP method says what to do, and the body is usually JSON. The most common shape.
- SOAP: every request and reply is an XML envelope, usually described by a WSDL file. Strict and verbose, but still common in HR, payroll and finance. Errors come back as a Fault element.
- GraphQL: usually one URL. You write a query that says exactly which fields you want back.
In GraphQL, a success code does not mean fine
A GraphQL reply can carry data and errors at the same time. The GraphQL-over-HTTP spec, still a draft, says that if some data came back, the status code must still be a 2xx success code, even when some fields failed.
{
"data": { "employee": { "name": "Sara", "salary": null } },
"errors": [
{ "message": "Not allowed to read salary", "path": ["employee", "salary"] }
]
}Example reply, the shape and not a real API. The data and errors keys, and the path inside each error, follow the GraphQL spec. This can arrive with a success status code.
The skills stay the same
The wrapping changes. The questions do not: auth, pagination, errors, limits and mapping fields. A new API style is the same checklist with different syntax.
Do this in 60 secondsFind the line where your code decides if a GraphQL call worked. If it only checks the status code, add a check for an errors list in the body.
Today’s AI angleAn AI agent sees a tool, not REST, SOAP or GraphQL. Someone has to turn a GraphQL errors list or a SOAP Fault into a clear failure. If a partial error is reported as success, the agent will tell the user the job is done.