06 — API Styles — REST, SOAP, GraphQL, and OpenAPI as One Spectrum

REST, SOAP, GraphQL, OpenAPI — four names I used to treat as a menu I had to pick from. Writing them down collapsed them into one spectrum: they differ along a single axis — how rigidly the server fixes the shape of requests and responses — and OpenAPI is the contract layer that makes any of them safe to consume. [1]

The framing that helped is what each style assumes about the client. SOAP assumes the client wants a strict, formal contract and will generate code from it. REST assumes the client speaks HTTP verbs on resource URLs and is happy with whatever shape the server returns. GraphQL assumes the client knows exactly which fields it wants and should be allowed to declare them. OpenAPI isn't an API style at all — it's a way to write the contract down so any REST API can be documented, validated, and code-generated against.

REST: resources, verbs, and statelessness

REST (Representational State Transfer) is the default — an architectural style that maps data to resources identified by URLs, and uses standard HTTP verbs to act on them [2]. GET /users/42 fetches a user; POST /users creates one; PUT /users/42 updates; DELETE /users/42 removes. The protocol is HTTP; the data format is almost always JSON.

Two principles define REST in practice:

• Statelessness. Every request contains everything the server needs to handle it. The server keeps no client state between requests — which makes REST horizontally scalable (any server can handle any request) and simple to reason about.
• Resource orientation. URLs name nouns (/users, /orders), not verbs. The HTTP method is the verb. This convention makes REST APIs discoverable and uniform.

REST's strength is its simplicity and the fact that it speaks HTTP natively — every platform, every tool, every firewall understands it. Its weakness is the fixed-shape problem: the server decides what a /users/42 response looks like, and every client gets that same shape whether it needs two fields or forty. That tension is exactly what GraphQL was built to address.

SOAP: the strict-contract enterprise option

SOAP (Simple Object Access Protocol) is the formal, XML-based message protocol that predates REST [3]. A SOAP API exposes operations (not resources) described by a WSDL contract — a strict XML schema that defines every operation, its inputs, and its outputs. Clients generate strongly-typed code from the WSDL; messages are XML envelopes exchanged over HTTP (or other transports).

SOAP's appeal is its rigor: the contract is formal, the messaging has built-in error handling and ACID-style reliability extensions (WS-*), and the code generation makes large APIs tractable. Its cost is weight — XML is verbose, the envelope overhead is significant, and the tooling is heavy. SOAP is now mostly an enterprise and legacy concern (payment gateways, banking, SOAP-era integrations). New APIs rarely choose SOAP, but backend devs meet it in existing systems.

gRPC: typed binary RPC for service-to-service

gRPC sits off the HTTP-JSON path — it's a high-performance RPC framework using Protocol Buffers as the interface definition language and binary wire format [4][5]. A .proto file declares the service (a set of methods with typed request/response messages), and the gRPC tooling generates client and server stubs in multiple languages. The wire format is binary (compact, fast), and gRPC runs over HTTP/2.

gRPC's strengths are performance and strong typing across languages — a Go service and a Python client share the same proto-defined contract. It's the common choice for internal service-to-service communication in microservice architectures where latency and type safety matter more than human-readability. Its weakness for public APIs is exactly that — the binary format and proto requirement make it less approachable than JSON-over-HTTP for outside consumers.

GraphQL: the client declares the shape

GraphQL flips the authority: instead of the server fixing the shape, the client writes a query describing exactly the fields it wants, and the server returns precisely those fields [6]. One endpoint, a typed schema, and queries that match the shape of the response.

The problem GraphQL solves is the fixed-shape tension under REST:

• Over-fetching — GET /users/42 returns thirty fields when the client needs two.
• Under-fetching — a screen needs a user and their posts, forcing two REST round trips.

GraphQL lets the client ask for name and posts { title } and get back exactly that. The trade-off is complexity: the server needs resolvers, the schema becomes a governance concern, and N+1 queries, authorization at every field, and caching all become the team's problem. GraphQL pays off when clients are varied (mobile, web, different screens wanting different slices); it's overkill for a uniform, stable API.

OpenAPI: the contract layer, not a style

OpenAPI (formerly Swagger) is the one that doesn't fit the spectrum because it isn't an API style — it's a specification format for describing REST APIs [7]. An OpenAPI document is a YAML or JSON file that declares every endpoint, its parameters, its request body schema, its response schemas, and its authentication requirements. It's the contract REST lacked by default.

What OpenAPI unlocks is tooling. From an OpenAPI spec I can generate:

• Interactive documentation (Swagger UI) that lets consumers try endpoints in the browser.
• Client libraries in any language — typed code that calls my API, generated automatically.
• Server stubs — the skeleton of the API implementation, in my language.
• Validation — every request and response checked against the schema at runtime.

The reason I flag OpenAPI separately is that it's the part of REST that brings it close to SOAP and gRPC's contract-first rigor without the weight. A REST API with an OpenAPI spec gets the documentation, type safety, and code generation that SOAP's WSDL used to provide. For any REST API with more than one external consumer, writing and maintaining the OpenAPI spec is now table stakes.

How I use this

The decision is a matching exercise, not a ranking:

• Default public API → REST + OpenAPI. HTTP verbs on resources, JSON responses, and an OpenAPI spec for documentation and code generation. The combination gets 90% of the benefit at 30% of the complexity.
• Internal service-to-service, latency-sensitive → gRPC. Typed proto contracts, binary wire, multi-language stubs. The contract is the proto file.
• Varied clients wanting different slices of the same data → GraphQL. When over-fetching and under-fetching are real and ongoing pains.
• Existing enterprise/legacy integration → SOAP. Not a greenfield choice, but one I'll encounter.

The habit that carries across all of them: the contract is the API. Whether it's an OpenAPI spec, a proto file, a GraphQL schema, or a WSDL, the written-down, validated, versioned contract is what makes an API safe to consume and evolve. Without it, I'm shipping vibes over HTTP.

References

[1] AWS, "What is an API?," 2024. [Online]. Available: https://aws.amazon.com/what-is/api/

[2] Red Hat, "What is a REST API?," 2024. [Online]. Available: https://www.redhat.com/en/topics/api/what-is-a-rest-api

[3] "SOAP Web Services Tutorial for Beginners," guru99. [Online]. Available: https://www.guru99.com/soap-simple-object-access-protocol.html

[4] gRPC Authors, "gRPC." [Online]. Available: https://grpc.io/

[5] "What Is gRPC?," Wallarm. [Online]. Available: https://www.wallarm.com/what/the-concept-of-grpc

[6] GraphQL Foundation, "Introduction to GraphQL," graphql.org, 2024. [Online]. Available: https://graphql.org/learn/

[7] "OpenAPI Specification," swagger.io. [Online]. Available: https://swagger.io/specification/