Every new project has the same debate: REST, GraphQL, or something else? SOAP gets dismissed, but it still runs half the world's banking infrastructure. Each of these has a distinct philosophy — and picking the wrong one means fighting your tooling for years.

REST: Resources and HTTP Semantics

REST treats everything as a resource with a URL, and uses HTTP verbs to express intent — GET to read, POST to create, PUT/PATCH to update, DELETE to remove. It's stateless, cacheable, and universally understood. REST is the default choice for public APIs because every language, framework, and developer already understands it.

# REST — resource-oriented, verb-driven
GET    /users/42
POST   /users
PATCH  /users/42
DELETE /users/42/posts/7

The REST Problem: Over-fetching and Under-fetching

REST's weakness is rigid response shapes. GET /users/42 returns everything whether you need it or not (over-fetching). If you need a user's posts and followers in one screen, you make 3 requests (under-fetching). This is what drove Facebook to build GraphQL.

GraphQL: Query What You Need

GraphQL exposes a single endpoint and lets clients declare exactly what data they need in a typed query language. The server returns precisely that shape — nothing more, nothing less. This eliminates over/under-fetching and is transformative for complex UIs with many data dependencies.

query {
  user(id: "42") {
    name
    email
    posts(last: 5) {
      title
      createdAt
    }
    followers {
      count
    }
  }
}

GraphQL Trade-offs

• ▸HTTP caching doesn't work natively — everything is POST to /graphql
• ▸N+1 query problems are real without DataLoader or batching
• ▸Schema design is hard to get right and painful to break once public
• ▸Excellent for frontend-heavy apps where UI teams own query shapes
• ▸Overkill for simple CRUD APIs — adds complexity without benefit

SOAP: Contracts, Envelopes, and Enterprise

SOAP is a protocol, not just a style. Messages are XML wrapped in a strict envelope structure with a WSDL contract defining every operation and type. It's verbose, complex, and unfashionable — but it has built-in WS-Security, ACID transaction support, and formal error handling that REST and GraphQL don't. Banks, insurance systems, and healthcare APIs use SOAP because the tooling around formal contracts and security is mature and auditable.

The Decision Framework

• ▸Public API with unknown consumers? → REST — universal, cacheable, well-understood
• ▸Complex frontend with many data shapes per screen? → GraphQL
• ▸Internal microservices needing performance and streaming? → gRPC
• ▸Enterprise integration with formal contracts, WS-Security, or legacy systems? → SOAP
• ▸Simple CRUD with a mobile app? → REST, possibly with a BFF (Backend for Frontend) pattern

The worst outcome is GraphQL adopted for a simple internal CRUD service, or REST used for a mobile app that makes 12 chained requests to render one screen. Match the paradigm to the actual problem.