Post

From SOAP to GraphQL in Distributed Systems

Posted
Preview Image
By Aykhan Tanirverdiyev
6 min read
From SOAP to GraphQL in Distributed Systems

In the landscape of modern software engineering, the ability for disparate systems to communicate effectively is paramount. As we move away from monolithic structures toward distributed systems, understanding the underlying paradigms of data exchange—specifically Service-Oriented Architecture (SOA), REST, and GraphQL—is essential for any backend engineer or security researcher.

1. The Paradigm Shift: Service-Oriented Architecture (SOA)

Before diving into protocols, we must establish the architectural foundation. Service-Oriented Architecture (SOA) allows us to build complex systems by composing them of autonomous, cooperating units known as services.

The core value proposition of SOA is interoperability in heterogeneous environments. A .NET-based accounting service must be able to communicate seamlessly with a Java-based inventory system.

Key Characteristics

  • Layered Implementation: Services typically abstract their internal logic (Database, Data Access Layer, Business Logic Layer) behind a public Service Interface.
  • Message-Based Communication: Unlike tight coupling in method calls within a single binary, SOA relies on standardized messages exchanged over a network.
  • Contract-Driven: A service publishes a contract defining its business functionalities (e.g., “CalculateTax” or “UpdateInventory”), decoupling the implementation from the consumer.

2. The Strict Standard: SOAP (Simple Object Access Protocol)

SOAP represents the “heavyweight” champion of the early web service era. It is a protocol, not just an architectural style, governed by strict standards (SOAP 1.1/1.2). While often considered legacy, it remains prevalent in enterprise environments requiring rigid contracts and advanced security features.

The Anatomy of a SOAP Message

SOAP utilizes XML exclusively. A message consists of an Envelope containing a Header (for metadata like security tokens) and a Body (the actual payload).

Hypothetical Scenario: Consider a Banking System. A request to transfer funds might look like this (conceptual XML):

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope/">
   <soap:Header>
       <Security>
           <Token>abc-secure-token-123</Token>
       </Security>
   </soap:Header>
   <soap:Body>
       <m:TransferFunds xmlns:m="http://bank.example.org/finance">
           <m:SourceAccount>889900</m:SourceAccount>
           <m:TargetAccount>112233</m:TargetAccount>
           <m:Amount>500.00</m:Amount>
       </m:TransferFunds>
   </soap:Body>
</soap:Envelope>

The Contract: WSDL

SOAP relies on the Web Service Description Language (WSDL). This XML document strictly defines operations, parameter schemas, and network locations.

Unlike REST, where documentation can sometimes be loose or ad-hoc, a WSDL document strictly defines three critical aspects of the service:

  1. Data Types: The exact schema of parameters and return types (e.g., ensuring a “price” is a decimal, not a string).
  2. Operations: The abstract definition of available methods (e.g., GetStockPrice, UpdateOrder).
  3. Binding & Address: The concrete protocol details (typically HTTP) and the physical network URL where the service lives.
    • Pros: Ideally, we never write WSDL manually. Frameworks (like WCF in .NET or JAX-WS in Java) generate the WSDL from code interfaces, and clients can auto-generate proxy classes from the WSDL, making remote calls feel like local method invocations.
    • Error Handling: SOAP defines a specific Fault element for errors, allowing standardized exception handling across different platforms.
    • WS- Standards: It supports advanced middleware specifications like WS-Security and WS-AtomicTransaction, which are often missing or ad-hoc in REST.

3. The Agile Architecture: REST (Representational State Transfer)

As the web exploded, the complexity of SOAP (and its XML overhead) led to the adoption of REST. Unlike SOAP, REST is an architectural style, not a strict protocol. It leverages the existing semantics of HTTP 1.1.

Core Principles

  1. Resource-Based: We do not think in terms of “operations” (verbs) like GetStockPrice. We think in terms of “resources” (nouns) like Stocks.
  2. Statelessness: The server does not maintain session state between requests. Every request must contain all necessary information (e.g., via tokens).
  3. Uniform Interface: We use standard HTTP verbs to manipulate resources.

RESTful Implementation Example: IoT Fleet Management

Imagine managing a fleet of smart sensors.

  • GET /api/sensors/42: Retrieves the state of sensor 42. (Idempotent, safe).
  • POST /api/sensors: Registers a new sensor. Returns 201 Created with a Location header pointing to the new resource.
  • PUT /api/sensors/42: Replaces the entire configuration of sensor 42. (Idempotent).
  • PATCH /api/sensors/42: Partially updates sensor 42 (e.g., just changing the firmware version). (Not idempotent) .
  • DELETE /api/sensors/42: Deletes the sensor.

Filtering and Relations: REST handles complexity via query strings and URL hierarchy:

  • GET /sensors?status=active&sort=-lastActive (Filtering active sensors, sorting by time descending).
  • GET /sensors/42/logs (Retrieving a related resource—logs specific to sensor 42).

The “Web API” Reality

In the .NET ecosystem, we often use the term Web API to describe services that use REST concepts over HTTP, even if they aren’t strictly “RESTful”. Often, developers make concessions, such as using RPC-style endpoints (e.g., POST /api/users/createMultiple) for complex batch operations that don’t fit the pure resource model.

In .NET Core / .NET 5+, we define these using Controllers:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[Route("api/[controller]")]
[ApiController]
public class SensorsController : ControllerBase
{
    // Maps to POST /api/sensors
    [HttpPost]
    public IActionResult Register([FromBody] Sensor sensor)
    {
        _db.Sensors.Add(sensor);
        _db.SaveChanges();
        // Returns 201 and the URL to the new item
        return CreatedAtAction(nameof(GetById), new { id = sensor.Id }, sensor);
    }
}

4. Documentation: The OpenAPI Standard (Swagger)

Because REST lacks the strict WSDL contract of SOAP, we need a way to describe our APIs. OpenAPI (formerly Swagger) has become the standard.

It uses JSON or YAML to define:

  • Available endpoints (/sensors).
  • Input/Output parameters and schemas.
  • Authentication methods (like OAuth2 or JWT).

Swagger UI provides an interactive HTML page where developers can explore and test endpoints directly in the browser—a massive quality-of-life improvement over raw WSDL files.

5. The Modern Alternative: GraphQL

While REST is dominant, it suffers from two specific data-fetching problems:

  1. Overfetching: Downloading a massive JSON object when you only needed one field (e.g., fetching a whole user profile just for the username).
  2. Underfetching: Needing to hit multiple endpoints (N+1 problem) to get related data (e.g., fetching a User, then fetching their Posts, then fetching Followers).

GraphQL, introduced by Facebook in 2015, solves this by offering a single endpoint for declarative data fetching.

The GraphQL Schema

GraphQL is strongly typed. You define a schema (SDL) that serves as the contract.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

type Movie {
  id: ID!
  title: String!
  director: Director!
  reviews(limit: Int): [Review!]!
}

type Director {
  name: String!
  movies: [Movie!]!
}

type Query {
  getMovie(id: ID!): Movie
}

The Query

The client defines exactly what it wants. If I only need the movie title and the director’s name, I ask only for that:

Request:

1
2
3
4
5
6
7
8

query {
  getMovie(id: "101") {
    title
    director {
      name
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10

{
  "data": {
    "getMovie": {
      "title": "Inception",
      "director": {
        "name": "Christopher Nolan"
      }
    }
  }
}

Unlike REST, where the server dictates the response structure, GraphQL empowers the client. This decouples frontend iterations from backend changes. However, this flexibility introduces security risks: a malicious client could construct a deeply nested, recursive query to exhaust server resources (DoS), requiring complexity analysis or depth limiting on the server.

Conclusion: Which to Choose?

  • Choose SOAP if you are integrating with legacy enterprise systems requiring strict WS-* security standards or formal contracts.
  • Choose REST for public-facing APIs, microservices, and general web applications. It scales well (stateless), supports multiple formats (JSON/XML), and utilizes standard HTTP caching.
  • Choose GraphQL for complex frontends (mobile/SPA) where network efficiency is critical, or when different clients need vastly different subsets of data from the same domain.

Attribution: This post is based on my interpretation of the “Web services, REST, WebAPI, GraphQL” lecture materials by Zoltán Benedek BME.

softeng, Data-Driven Systems
REST API SOAP GraphQL WebAPI
This post is licensed under CC BY 4.0 by the author.