← Integration Engineering
Integration Engineering

Not Every API Is REST: Reading SOAP and GraphQL Without Panic

12 Oct 2026·3 min read

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.
Not Every API Is REST: Reading SOAP and GraphQL Without Panic · Ali Huzaifa