API Migration Journey

On working recent api migration, it triggered me to write comprehensive and suitable journey of API design growth for a technical audience. 

SOAP

• Illustration:

  • SOAP Sender: Represents a client application initiating a request.

  • Protocol (HTTP/SMTP): The transport layer over which SOAP messages are sent. Messages are typically XML-based.

  • SOAP Message (Envelope): A structured XML document containing the message body, header, and fault information.

  • SOAP Receiver: A server-side application parsing the SOAP message, processing the request, and sending a SOAP response.

  • Key Characteristics:

    • Strictly Typed: Uses XML Schema Definition (XSD) for message structure.

    • WSDL: Web Services Description Language describes the operations a web service offers.

    • Stateless: Each request is independent.

    • Synchronous/Asynchronous: Can support both.

    • Security: Built-in WS-Security standards.

    • Reliability: WS-ReliableMessaging for guaranteed delivery.

• Use Case: Enterprise-level financial transactions, legacy system integration, highly distributed environments requiring ACID transactions and formal contracts.

• Pros: High reliability, security, ACID compliance, language independence, extensive tooling.

• Cons: Complex, verbose XML, higher overhead, steeper learning curve.

REST

• Illustration:

  • Sender (Client): Sends HTTP requests (GET, POST, PUT, DELETE) to a server.

  • HTTP Request: Contains method, URL, headers, and optional body.

  • REST Web Server: Processes requests, accesses resources, and sends back HTTP responses.

  • HTTP Response: Contains status code, headers, and resource representation (e.g., JSON, XML).

  • Key Characteristics:

    • Stateless: Server doesn't store client context between requests.

    • Cacheable: Responses can be cached to improve performance.

    • Client-Server: Clear separation of concerns.

    • Layered System: Intermediaries (proxies, load balancers) can be introduced.

    • Uniform Interface: Resources identified by URIs, standard HTTP methods.

    • Self-Descriptive Messages: Messages contain enough info to be processed.

    • HATEOAS (Hypermedia As The Engine Of Application State): Optional, but a core principle for discoverability.

• Use Case: Mobile application backend for a social networking platform, public APIs, web services requiring scalability and simplicity.

• Pros: Simple, flexible, widely adopted, efficient (JSON is light), scalable, cacheable.

• Cons: No strict contract (can lead to integration issues), lack of type safety, under/over-fetching data for complex queries.

GraphQL

• Illustration:

  • Sender (Client): Sends a single HTTP POST request to a GraphQL server.

  • GraphQL Query/Mutation: A flexible query string defining exactly what data the client needs.

  • GraphQL Server: Parses the query, resolves fields by interacting with various data sources (databases, other APIs), and constructs a single JSON response.

  • Database/Other APIs: Data sources from which the GraphQL server fetches information.

  • Key Characteristics:

    • Single Endpoint: All queries go to one URL.

    • Declarative Data Fetching: Clients specify data requirements.

    • Schema Definition Language (SDL): Defines types, fields, and relationships.

    • Resolvers: Functions that fetch data for specific fields.

    • Strongly Typed: Prevents many runtime errors.

    • No Over/Under-fetching: Clients get exactly what they ask for.

• Use Case: Real-time collaborative document editing, complex UIs needing data from multiple sources, microservices aggregation layer, mobile applications to reduce network requests.

• Pros: Efficient data fetching, strong typing, better developer experience (IDE support), versionless APIs.

• Cons: Caching complexity (due to POST requests), steeper learning curve than REST for basic use, file upload can be tricky.

gRPC

• Illustration:

  • Client (abc): Makes a remote procedure call to a server.

  • Protocol Buffers (010010): A language-neutral, platform-neutral, extensible mechanism for serializing structured data. Used for defining service interfaces and message structures.

  • gRPC Server (Database Icon): Receives the call, executes the procedure, and returns a response.

  • HTTP/2: The underlying transport layer for multiplexing, streaming, and efficient connections.

  • Key Characteristics:

    • Contract-First: Uses Protocol Buffers (or other IDLs) to define service methods and message types.

    • High Performance: Binary serialization (Protobufs) and HTTP/2 for efficient data transfer.

    • Streaming: Supports unary, server-side, client-side, and bi-directional streaming.

    • Polyglot: Code generation for many languages.

    • Strongly Typed: Ensured by Protobuf definitions.

• Use Case: Microservices communication in a distributed system, inter-service communication, high-performance computing, real-time data streaming.

• Pros: High performance, low latency, efficient serialization, strong contracts, multi-language support, built-in streaming.

• Cons: Browser support requires a proxy, not human-readable payload, steeper learning curve, limited tooling compared to REST.

Websocket

• Illustration:

  • Sender (Client): Initiates an HTTP Upgrade request to establish a WebSocket connection.

  • HTTP Upgrade: Handshake process to upgrade from HTTP to WebSocket protocol.

  • Web Server (Building): Accepts the upgrade, establishing a persistent, full-duplex connection.

  • Full Duplex: Both client and server can send and receive messages simultaneously over the same open connection.

  • Key Characteristics:

    • Persistent Connection: A single, long-lived connection.

    • Full-Duplex: Bi-directional communication.

    • Low Overhead: After the initial handshake, minimal frame overhead.

    • Real-time: Ideal for immediate data exchange.

    • Event-Driven: Messages pushed from server to client.

• Use Case: Live sports score updates, chat applications, real-time dashboards, online gaming, stock tickers.

• Pros: Real-time communication, low latency, efficient for frequent small messages, reduced server load compared to polling.

• Cons: More complex to implement than HTTP requests, requires server infrastructure to manage persistent connections, no built-in error handling/retries like HTTP.

Webhook

• Illustration:

  • Source Application (Server with Gears): An event occurs (e.g., order fulfillment).

  • Async (Red Dotted Line): The source application asynchronously sends an HTTP POST request.

  • Payload (Gear Icon in Box): The POST request contains data about the event, typically JSON.

  • Webhook Listener/Receiver (Server Stack): A designated URL (endpoint) on a different server that is configured to receive these notifications.

  • Automated Order Fulfillment: The receiving system processes the event data.

  • Key Characteristics:

    • Event-Driven: Triggered by specific events.

    • HTTP POST: Typically uses POST requests to deliver data.

    • Asynchronous: The source doesn't wait for a response from the receiver.

    • Subscription Model: The receiver "subscribes" to events from the source by providing a callback URL.

    • Payloads: Data included in the POST request.

    • Retries/Error Handling: Often implemented by the source application for reliability.

• Use Case: Automated order fulfillment notifications in e-commerce, GitHub commit notifications, payment gateway callbacks, CRM updates, CI/CD pipeline triggers.

• Pros: Real-time updates, reduced polling overhead, efficient for event propagation, simple to implement for basic use cases.

• Cons: Requires the receiver to have a publicly accessible URL, security concerns (verifying source), managing retries and failures, potential for "noisy" notifications if not filtered.