11 — APIs and Integration — REST, gRPC, GraphQL, and the Rest

REST, GraphQL, gRPC, SOAP, queues, BPM — the integration sprawl looked like a fashion contest until the trade-offs appeared. The model that made it navigable: every integration style is a point on a small set of trade-offs — simplicity, performance, contract strictness, and whether the parties are decoupled in time [1]. Once I could place each option on those axes, the "which API style" question stopped being a fashion contest and became a fit exercise.

APIs and integrations define how different systems and services communicate [1]. Choosing the right integration style, protocol, and data format affects performance, flexibility, and how easily new systems connect later. This is a core concern in almost every modern architecture, since few systems operate in isolation.

Synchronous, request/response: REST and GraphQL

The first axis is whether the caller waits for a response. The two dominant synchronous styles are REST and GraphQL, and they sit at different points on the flexibility axis.

REST is an architectural style for designing APIs around resources, identified by URLs and manipulated through standard HTTP methods (GET, POST, PUT, DELETE) [2]. Its simplicity and reliance on existing web standards made it the most common approach for public and internal APIs. Architects favor REST when they need a widely understood, easy-to-consume interface. The trade-off: the server decides the response shape, which leads to over-fetching and under-fetching when clients have varied needs.

GraphQL lets the client declare exactly the fields it wants, and the server returns precisely that — one endpoint, one typed graph, the query is the shape of the response [3]. It's particularly useful for mobile (bandwidth efficiency) and for applications with diverse client requirements. While it requires a paradigm shift from REST, many organizations find the benefits outweigh the learning curve for large-scale or rapidly evolving APIs [3]. The trade-off: more server-side complexity (resolver functions for each field, rules to govern the shared schema, and the N+1 risk — one query fanning out into many separate database calls) for that client flexibility.

Fast and typed, internal: gRPC

gRPC is a high-performance remote-procedure-call framework using HTTP/2 and Protocol Buffers for fast, efficient service-to-service communication [4]. It supports streaming and strongly typed contracts, making it a common choice for internal microservices communication. Compared to REST, gRPC generally offers better performance but is less human-readable and less suited to public-facing APIs [4]. The trade-off: strict binary contracts and speed, at the cost of the readability and ubiquity that make REST easy to consume from anywhere.

The legacy enterprise stack: ESB and SOAP

ESB (Enterprise Service Bus) and SOAP (Simple Object Access Protocol) are the integration technologies of the pre-microservices enterprise [5]. The ESB is a software architecture that integrates various systems — databases, web services, mobile apps — through a central bus that routes and transforms messages. SOAP is the messaging protocol that exchanges structured data (XML envelopes) between systems over the network. These predate REST and microservices, typically involve heavier middleware, and many large enterprises still run them. An architect integrating with brownfield enterprise systems will meet SOAP and ESB whether they like it or not.

Decoupled in time: messaging queues

The next axis is temporal decoupling. Message queues let applications communicate asynchronously — the sender writes a message to a queue and continues working immediately, without waiting for the receiver [6]. The queue provides temporary storage between sender and receiver, so the sender isn't blocked if the destination is busy or offline. This decouples the parties in time and is the foundation of event-driven architectures: an order-service publishes an event, and billing and shipping each consume it at their own pace. The trade-off against synchronous calls is added infrastructure and the cognitive cost of eventual-consistency reasoning.

Business-process orchestration: BPM and BPEL

At the top of the integration stack sits business process management (BPM) — methodologies and tools for modeling, automating, and optimizing business processes across an organization [7]. BPEL (Business Process Execution Language) is the XML-based language used to define and orchestrate these processes, often within service-oriented architectures. Architects working on enterprise workflow automation need to understand how BPM tools coordinate multiple systems to complete a business process — a long-running flow that spans services, with retries, human steps, and state [7]. This is the layer above individual API calls: not "how does service A call service B," but "how do services A through F combine to fulfill a loan application end-to-end."

How I use this

I place each integration need on two axes: synchronous versus asynchronous, and simple versus strictly contracted. Public, varied clients lean REST or GraphQL (GraphQL when shapes vary a lot). Internal, performance-sensitive service-to-service leans gRPC. Anything that needs to survive a consumer being down or slow leans messaging. Brownfield enterprise integration means accepting SOAP/ESB where they live. And long-running cross-system workflows are a BPM concern, not an API concern — trying to encode them purely in REST calls is how teams end up with distributed spaghetti. The discipline is matching the style to the integration's actual temporal and contractual needs.

References

[1] "APIs and Integrations," roadmap.sh — Software Architect. [Online]. Available: https://roadmap.sh/software-architect/apis--integrations

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

[3] "GraphQL," roadmap.sh — Software Architect. [Online]. Available: https://roadmap.sh/software-architect/graphql

[4] "gRPC Introduction," gRPC.io. [Online]. Available: https://grpc.io/docs/what-is-grpc/introduction/

[5] "ESB and SOAP," roadmap.sh — Software Architect. [Online]. Available: https://roadmap.sh/software-architect/esb-soap

[6] Amazon Web Services, "Message Queues," [Online]. Available: https://aws.amazon.com/message-queue/

[7] Red Hat, "What is BPM?," [Online]. Available: https://www.redhat.com/en/topics/automation/what-is-business-process-management