Post

API Architectural Styles - SOAP, REST, GraphQL, gRPC, WebSocket and Webhooks

Posted Updated
By Ramesha C Gowda 10 min read

Introduction

APIs are the backbone of modern software design and integration, enabling seamless communication between disparate systems. SOAP and REST have long dominated the enterprise for their structured and accessible approaches. Modern alternatives like GraphQL, gRPC, WebSocket, and Webhooks offer greater flexibility, enhanced performance, and real-time capabilities. Each architectural style brings unique strengths, allowing software architects and engineers to choose the best fit for specific use cases and operational demands.

These API styles sample endpoints can be tested by importing into Postman Collections. https://github.com/rameshagowda/api-styles

API Test strategy is important to consider for automation which is provided in the end.

1. SOAP

SOAP is an XML-based protocol with a robust, standardized contract defined via WSDL, which ensures secure and reliable communication in enterprise environments. It is ideal for systems that require strict message formatting, built-in error handling, and formal transaction support.

ASMX (in the example) refers to the file extension used for legacy SOAP-based web services in Microsoft’s ASP.NET framework. These “.asmx” files serve as endpoints that automatically handle SOAP messaging—packaging, transmitting, and receiving XML messages according to the SOAP protocol.

How to make SOAP request using Postman?

  1. Use this SOAP endpoint to test - https://www.w3schools.com/xml/tempconvert.asmx
  2. Select POST from the request method dropdown list.
  3. In “Headers” tab,
  • Add Content-Type to “application/soap+xml; charset=utf-8”
  • SOAPAction to “#POST”
  1. In the Body tab, select raw and choose XML from the dropdown list.This is how sample request and response looks like for a SOAP endpoint. Desktop View

References

https://learning.postman.com/docs/sending-requests/soap/making-soap-requests/ https://blog.postman.com/making-http-soap-requests-with-postman/

2. REST

REST uses standard HTTP methods to manipulate resources, typically exchanging data in JSON or XML. Its stateless, lightweight nature makes it highly scalable and easy to integrate with web and mobile applications.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

  - GET example

    URL: https://jsonplaceholder.typicode.com/posts

    Method: GET

    Returns: A list of sample posts in JSON format.


  - POST example

    URL: https://jsonplaceholder.typicode.com/posts

    Method: POST

    Headers: Content-Type: application/json

    Body (raw JSON): {
          "title": "New Post Title",
          "body": "This is the content of the post.",
          "userId": 1
          }

1

    curl --location 'https://jsonplaceholder.typicode.com/posts'

1
2
3
4
5
6
7
8

    curl --location 'https://jsonplaceholder.typicode.com/posts' \
    --header 'Content-Type: application/json' \
    --data '{
      "title": "YET ANOTHER Post Title",
      "body": "This is the content of the post.",
      "userId": 1
    }
    '

References

3. GraphQL

Unlike REST, which uses multiple endpoints to access different data sets, GraphQL streamlines querying by accessing all data through a single endpoint. It lets clients specify exactly which fields they need, eliminating over-fetching and under-fetching inherent in traditional REST designs. With its strongly typed schema and flexible query language, GraphQL enables more efficient, self-documenting, and evolvable APIs.

GraphQL requests can perform three types of operations:

1
2
3
4
5

  - Query - Retrieves data from the server. Queries specify the required data fields and can include arguments for more precise data retrieval.

  - Mutation - Manipulates data on the server, including creating, updating, or deleting records. Mutations specify the fields to be returned after the operation and use arguments to detail the manipulation.

  - Subscription - Gets real-time data updates from the server. Subscriptions enable clients to listen to specific data fields and receive updates automatically over a persistent connection.

  • GraphQL Queries and Mutations use Http POST mainly because POST avoids URL length limitations and better accommodates complex queries and payloads.

  • Subscriptions are designed for real time updates and typically run over a persistent connection using WebSockets.

Desktop View

References

4. gRPC

gRPC is fundamentaly a contract-first design, meaning you always start with a “contract”, typically defined in a “.proto” file that specifies your service interface and the message types exchanged between the client and the server.

Here are the important concepts in gRPC.

  1. Contract-First Design: gRPC starts with a contract defined by a Protocol Buffers (.proto) file. This file specifies the service, the available RPC methods, and the structure of the request and response messages. This contract-first approach ensures both the server and client adhere to a consistent API specification.

    • Think of Service definitions and messages like Interfaces and DTOs in DotNet.

  2. Transport Over HTTP/2: This means TLS only and supports multiplexing, header compression and full duplex communication.

  3. Efficient Serialization with Protocol Buffers: Protocol Buffers (protobuf) provide a compact binary serialization mechanism. Compared to text-based formats like JSON, protobufs result in smaller payloads and faster serialization/deserialization (encoding/decoding), making data transfer more efficient.

  4. Flexible RPC Communication Patterns:

    • Unary RPC: A single request followed by a single response.

    • Server Streaming RPC: The client sends a request and receives a stream of responses.

    • Client Streaming RPC: The client sends a stream of requests and gets back one response.

    • Bidirectional Streaming RPC: Both client and server send streams of messages concurrently, ideal for real-time communications.

Architecture of gRPC

Desktop View

Design Process for gRPC implementation

  1. Define the Service Contract Using a Proto File
    • Defines the Service, methods and messages (data contract/DTOs)
  2. Generate Code from the Proto File
    • Use Protocol Buffers compiler (protoc) to generate the client code (Stubs) and server side abstract base class code (Skeleton).
  3. Implement the Server - base class skeleton
    • Extend the generated base class to implement the contracts that provide required functionality and run the gRPC server.
  4. Implement the Client - Stub
    • Stub leverages the channel to connect to server and invoke RPC methods.
  5. Run and Test the Application

Protocol Buffers vs JSON

JSON

Desktop View

ProtoBuf

Desktop View

References

5. WebSocket

WebSockets establish a persistent connection between client and server, enabling realtime, bi-directional data exchange without repeated HTTP handshakes.

After an initial HTTP upgrade, they use a dedicated protocol over TCP, reducing overhead and latency for interactive applications.

They are widely used for chat, gaming, live updates, and other scenarios where continuous, rapid data transmission is essential.

Socket.io (NodeJS) and SignalR (MS DotNet) leverage WebSockets for realtime, reliable and low latency communications. They can fallback to other transport protocols like SSE (Server Sent events) or long polling if websocket connection is not supported by client or network environment.

  1. Get the WS server endpoint. for ex, wss://ws.postman-echo.com/raw
  2. In postman, Create New –> WebSocket request –> Use the WSS endpoint
  3. Connect to WSS. You will see the status “Connected”
  4. Send the json request
  5. You will see the streaming response.

Desktop View

References

Difference between Http Polling, SSE (Server Sent Events), WebSockets and Webhooks.

WebSockets design and testing

6. Webhooks

A webhook API is an event-driven mechanism where one application automatically sends real-time data to another application when a specific event occurs. Instead of waiting for a client to poll an API for new information, the server “pushes” the data immediately to a predetermined URL endpoint via an HTTP POST request, thereby reducing overhead and ensuring timely updates.

Examples:

  1. Sending Notifications / Alerts on Teams or Salck when a CPU utilization reaches 80% in production systems.
  2. Automatically notifying an inventory system when a new order is placed.

How Webhooks work?

1
2
3
4
5
6
7

  - Event Occurrence: System A experiences or detects an event.

  - Subscription: System B (the recipient) registers its interest in that event by providing a target URL (its webhook endpoint) to System A.

  - Notification: When the event happens, System A sends an HTTP POST request containing the event data to the registered URL hosted by System B.

  - Processing: System B receives the payload and processes the data according to its logic (ex, updating its records or triggering specific workflows).

References

Difference between Http Polling, SSE (Server-Sent Events), WebSockets and Webhooks.

Mix API styles in the same Product?

1
2
3

  Yes, of course, we can use all of them together to execute an API strategy. Each API styles are best suited for certain use cases. For example, REST APIs are user friednly and can be used to expose to external users. gRPC is best suited for internal client server use cases like in microservices. So we can provide REST endpoints to external users, but internal transactions, calculations, communications can be handled with gRPC.

  - <https://github.com/DanielSCrouch/grpc-rest-openapi>

API styles in one image

Desktop View

API Protocols

Streaming Protocols

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

  - WebSocket

    Purpose: Enables full duplex, bidirectional streaming communication. Ideal for server to server applications like one api service talking to another api service to send and receive data.

    Underlying Protocol: Initiated via an HTTP handshake, then it upgrades to a persistent TCP connection.

  - Server Sent Events (SSE)

    Purpose: Provides a unidirectional, continuous stream of events from server to client. Response from ChatGPT in chunks is an example of SSE.

    Underlying Protocol: Uses a single long‑lived HTTP GET request with the text/event-stream MIME type.

  - gRPC (Streaming Calls)

    Purpose: Supports long lived RPC streams including server, client, and bidirectional streaming methods.

    Underlying Protocol: Built on HTTP2 with Protocol Buffers for serialization.

  - WebRTC

    Purpose: Facilitates realtime, peer to peer streaming of media (audio, video) and data. Ideal for client-side, or browser based applications like in voice chat conversation.

    Underlying Protocol: Uses UDP

  - GraphQL Subscriptions

    Purpose: Allows clients to subscribe to real‑time updates of the data they query.

    Underlying Protocol: Typically implemented over WebSockets (or sometimes SSE), inheriting its streaming qualities.

  - Messaging Protocols (e.g., AMQP, MQTT)

    Purpose: Provide continuous, event driven messaging often in a publish subscribe model suitable for IoT and distributed systems.

    Underlying Protocol: Primarily based on TCP (and can be tunneled over WebSockets in certain setups).

Request Response based (Nonstreaming) protocols

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

  - REST

    Purpose: Uses HTTP methods to perform operations on resources in a stateless fashion.

    Underlying Protocol: HTTP with payloads typically in JSON or XML.

  - SOAP

    Purpose: An XML‑based protocol emphasizing formal operations, transactions, and standardized error handling.

    Underlying Protocol: Commonly over HTTP, though it can also run over SMTP or raw TCP in some configurations.

  - GraphQL (Queries/Mutations)

    Purpose: Allows clients to request exactly the data they need in a single endpoint interaction.

    Underlying Protocol: Generally uses HTTP POST requests (JSON payloads), performing discrete queries or mutations.

  - gRPC (Unary Calls)

    Purpose: Executes standard procedure calls in a request‑response format without maintaining a persistent streaming channel.

    Underlying Protocol: Operates over HTTP/2 with Protocol Buffers for efficient encoding.

  - Webhooks

    Purpose: Implements an event-notification model where the server makes an HTTP POST call to a pre‑configured client endpoint when an event occurs.

    Underlying Protocol: Pure HTTP callbacks without a continuous connection.

API test automation strategy

  • Unit Test
  • Integration Test
    • Using Mocks
    • Using variables to exchange info between API calls
  • Contract test and Schema validation
  • End to end API test
    • Functional Test
    • Load and Performance Test
    • SQL Injection security check
    • Regression Testing

References for API tests using Postman

API, Architecture, Automation, Testing
api testing postman
This post is licensed under CC BY 4.0 by the author.