API Types & Architectures

Different architectural patterns and protocols for building APIs. Understanding these API types helps documentarians choose appropriate documentation approaches, explain implementation differences to users, and recognize when standard REST documentation conventions don't apply.

---

AMQP

Definition: acronym for Advanced Message Queuing Protocol - open standard application layer protocol for message-oriented middleware that enables reliable, asynchronous communication between applications

Purpose: provides interoperable wire format for messaging systems; supports message queuing, routing, reliability guarantees, and security features across different platforms and programming languages

Why this belongs in API Types & Architectures: AMQP is a messaging protocol specification ratified by OASIS - Organization for the Advancement of Structured Information Standards - and ISO - International Organization for Standardization - that defines message format and transmission, similar to how HTTP defines request-response communication; while tools like RabbitMQ implement AMQP, the protocol itself belongs with other communication protocols and architectural patterns

Example: financial services use AMQP to ensure reliable message delivery between trading systems, with guaranteed delivery options of at-most-once, at-least-once, or exactly once

Related Terms: AsyncAPI, HTTP, Kafka, MQTT, request-response, STOMP, WebSocket API

Sources:

• OASIS, AMQP About Page: "AMQP is the Internet Protocol for Business Messaging"
• Wikipedia: "Advanced Message Queuing Protocol"

---

API gateway

Definition: server that acts as a single entry point for many backend services, handling request routing, authentication, rate limiting, and response transformation

Purpose: simplifies client integration by providing a unified interface to many microservices; enables centralized security, monitoring, and versioning without clients needing to know about backend architecture

Example: an e-commerce API gateway routes /products requests to the product service, /orders to the order service, and /users to the user service, while handling authentication for all three

Related Terms: API, API endpoint, microservices, rate limiting

Source: F5, Inc., NGINX: "What Is an API Gateway?"

---

event-driven

Definition: architectural pattern where actions trigger in response to specific events rather than through continuous polling or scheduled intervals

Purpose: improves efficiency and responsiveness by processing only when relevant changes occur; reduces unnecessary network traffic and server load

Example: a webhook API notifies an e-commerce system when payment completes, triggering immediate order fulfillment rather than checking payment status every few minutes

Related Terms: API, AsyncAPI, Kafka, Microcks, real-time, Server-Sent Events, webhook API, WebSocket API

Source: Amazon Web Service, Inc., (AWS): "What is an Event-Driven Architecture?"

---

GraphQL API

Definition: uses GraphQL - a query language and runtime - to let clients request exactly the data they need through a single endpoint with a strongly typed schema

Purpose: compared to REST APIs, reduces over-fetching and under-fetching of data; provides strongly typed schema and introspection capabilities for self-documenting APIs; particularly valuable for complex, interconnected data models; GraphQL can test query validation, field-level access controls, and schema compliance

Why this belongs in API Types & Architectures: GraphQL is both a query language and an architectural approach that fundamentally defines API design, structure, and function; unlike AsyncAPI and OpenAPI Specification which are documentation formats for describing existing APIs, GraphQL is the API implementation itself - it determines endpoint structure, data fetching patterns, and client-server interaction models; belongs alongside REST API and WebSocket API as an architectural pattern rather than in Core Concepts with documentation specification formats

Example: instead of calling /users/123, /users/123/posts, and /users/123/followers separately, a client queries one endpoint requesting

{ user(id: 123) { name, posts { title }, followers { name } } }

Related Terms: API, AsyncAPI, Mercure, Microcks, REST API, schema, validation

Sources:

• The GraphQL Foundation: "Learn GraphQL"
• Silva, Manny. Docs As Tests. First edition, Release 2, Boffin Education, May 2025.

---

gRPC API

Definition: uses gRPC - Google's Remote Procedure Call - framework, which relies on Protocol Buffers for serialization and HTTP/2 for transport

Purpose: enables high-performance, strongly typed communication between services; common in microservices architectures where efficiency and type safety matter more than human readability

Example: a payment processing service exposes gRPC methods like ProcessPayment() that accept and return strongly typed Protocol Buffers messages rather than JSON

Related Terms: API, HTTP versions, Microcks, Protocol Buffers, RPC API, serialization

Source: gRPC Authors: "What is gRPC?"

---

JSON-RPC

Definition: acronym for JavaScript Object Notation-Remote Procedure Call; lightweight remote procedure call protocol that uses JSON to encode messages; allows clients to invoke methods on a server and receive results, treating API interactions as direct function calls rather than resource-oriented requests

Purpose: provides a language-agnostic way to call server-side methods from client applications; particularly useful for internal microservices, blockchain APIs, and AI integrations where operations are better expressed as "execute this function" rather than "manipulate this resource"; differs from REST by focusing on actions/methods rather than resources/nouns, making it well-suited for procedural or command-based APIs

JSON-RPC vs REST

Aspect	JSON-RPC	REST API
Mental model	Remote function calls	Resource manipulation
Endpoint structure	Single endpoint, method in request body	Multiple endpoints representing resources
HTTP methods	Typically POST only	GET, POST, PATCH, PUT, DELETE
Request format	{"jsonrpc": "2.0", "method": "...", "params": [...]}	URL path + query params + body
Error handling	Structured error objects with codes	HTTP status codes
Common use cases	Blockchain APIs, internal services, AI protocols	Web APIs, CRUD operations, public APIs

Example: calling a method to get user information

// Request
{
  "jsonrpc": "2.0",
  "method": "getUserInfo",
  "params": {"userId": 123},
  "id": 1
}

// Response
{
  "jsonrpc": "2.0",
  "result": {
    "id": 123,
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com"
  },
  "id": 1
}

// Error Response
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  },
  "id": 1
}

Common Use Cases:

• blockchain and cryptocurrency APIs - Ethereum nodes, Bitcoin RPC
• internal microservices communication
• AI assistant protocols - Model Context Protocol
• real-time communication systems
• legacy system integrations

Related Terms: CRUD, HTTP status codes, JSON, MCP server, microservices, real-time, REST API

Sources:

• MPCM Technologies LLC, Matt Morley, JSON-RPC Working Group: "JSON-RPC 2.0 Specification"
• Wikipedia: "JSON-RPC"

---

Mercure

Definition: open protocol for pushing real-time data updates from servers to web browsers and HTTP clients, built on top of Server-Sent Events and HTTP

Purpose: provides modern alternative to WebSocket with features like automatic reconnection, authorization, state reconciliation, and native browser support; especially useful for adding real-time, streaming, and asynchronous capabilities to REST and GraphQL APIs

Example: API Platform uses Mercure to automatically push resource updates to connected clients when Doctrine entities change, enabling reactive web applications without custom WebSocket code

Related Terms: GraphQL API, REST API, Server-Sent Events, WebSocket API

Sources:

• Mercure Documentation: "Mercure in a Few Words"
• IETF: "The Mercure Protocol"

---

microservices

Definition: architectural approach in which applications are collections of small, independently deployable services that communicate via APIs

Purpose: enables teams to develop, deploy, and scale services independently; improves fault isolation and technology flexibility compared to monolithic architectures

Example: Netflix's streaming platform uses hundreds of microservices for recommendations, playback, billing, and user profiles, each with its own API

Related Terms: API, API gateway, JSON-RPC, REST API

Source: Martin Fowler: "Microservices"

---

MQTT

Definition: acronym for Message Queuing Telemetry Transport - lightweight publish-subscribe messaging protocol designed for constrained devices and networks with limited bandwidth or unreliable connections

Purpose: enables efficient IoT - Internet of Things - and machine-to-machine communication with minimal code footprint, low network overhead, and quality of service levels for delivery guarantees; optimized for battery-powered devices; used in a wide variety of industries, such as automotive, manufacturing, telecommunications, and oil and gas

Why this belongs in API Types & Architectures: MQTT is a messaging protocol standard ratified by OASIS - Organization for the Advancement of Structured Information Standards - and ISO - International Organization for Standardization - that defines communication patterns and message format, not a specific software implementation; comparable to how AMQP and WebSocket are protocol specifications in this category

Example: IoT devices like smart thermostats and industrial sensors use MQTT to publish temperature and pressure data to cloud brokers with minimal battery drain, leveraging persistent sessions that survive network disconnections and automatic reconnection capabilities

Related Terms: AMQP, AsyncAPI, HTTP, Kafka, STOMP, WebSocket API

Sources:

• MQTT.org: "MQTT - The Standard for IoT Messaging"
• Amazon Web Services, Inc.: "What is MQTT?"

---

real-time

Definition: describes systems and/or APIs that process and deliver data with minimal delay, enabling immediate responses to events as they occur

Purpose: supports use cases requiring instant updates like live notifications, streaming data, collaborative editing, and monitoring dashboards

Example: a WebSocket API delivers stock price changes to trading applications within milliseconds of market movements

Related Terms: event-driven, JSON-RPC, kinetic content, liquid content, Server-Sent Events, webhook API, WebSocket API

Sources:

• Mozilla Corporation, MDN: "WebRTC API (Web Real-time Communication)"
• Wikipedia: "Real-time computing"

---

REST API

Definition: acronym for Representational State Transfer API - one of the most widely used approaches for building web-based APIs

REST isn't a regulated standard, but an architectural style for distributed hypermedia systems, first presented by Roy Fielding in 2000; REST is a convention, used by APIs exposed through HTTP/HTTPS web services to exchange data.

Key Characteristics:

• Client-Server Architecture: assumes "clients," resource users, and "servers," resource providers
• Stateless: clients maintain the complete state of the interaction; servers provide only self-contained resources
• Cacheable: resources saved locally to improve performance
• Uniform Interface: standardized way of communicating between client and server
• Uses HTTP Methods: DELETE (remove), GET (read), PATCH (edit), POST (create), PUT (replace)
• Commonly uses JSON: due to its wide support in programming languages, REST APIs use JSON, but it's not required and also support other formats like XML

Example Request:

GET http://localhost:3000/users/2

Break down this URL:

• How: Uses the GET method of the HTTP protocol
• Where: From localhost:3000 server
• What: users/2 instance of this resource

Example Response:

GET requests a user resource, and the response body contains the resource formatted as a JSON document:

{
  "id": 2,
  "first_name": "Ferdinand",
  "last_name": "Smith",
  "email": "f.smith@example.com"
}

Related Terms: API, API documentation testing, CLI, HTTP, HTTP status codes, JSON, parameters, resource, URL

Sources:

• UW API Docs: Module 5, Lesson 1, "REST API Fundamentals"
• RESTful API: "What is REST?" by Lokesh Gupta

---

REST vs RESTful

Definition: terms are often used interchangeably, though technically "REST" refers to the architectural style itself while "RESTful" describes APIs that follow REST principles; in practice, both terms describe APIs that use HTTP methods, stateless communication, and resource-based URLs

Purpose: understanding this distinction helps API documentation writers use consistent terminology; while some sources differentiate between the two, most modern API documentation treats them as synonyms; what matters is plainly explaining whether an API follows REST architectural constraints rather than debating terminology

Example: documentation might say "this RESTful API uses HTTP methods" or "this REST API returns JSON responses" - both are acceptable; the key is explaining the API's behavior: stateless requests, resource-based endpoints like /users/123, standard HTTP methods - GET, POST, PUT, DELETE

Related Terms: API endpoint, HTTP, HTTP method, resource, REST API

Sources:

• RESTful API: "What is REST?" by Lokesh Gupta
• Roy Thomas Fielding's University of California Dissertation: Chapter 5 - "Representational State Transfer (REST)"

---

RPC API

Definition: acronym for Remote Procedure Call API; allows clients to execute functions on remote servers as if calling local functions, abstracting network communication details

Purpose: simplifies distributed computing by making remote operations look like local function calls; common in internal service-to-service communication

Example: a client calls getUserProfile(userId) which executes on a remote server and returns the result, hiding the network request details

Related Terms: API, gRPC API

Source: Geeks for Geeks: "Difference Between REST API and RPC API"

---

Server-Sent Events

Definition: also known as SSE; standard enabling servers to push real-time updates to web browsers over HTTP through unidirectional event streams from server to client; first specified by Ian Hickson in 2004

Purpose: provides alternative to WebSocket for server-to-client streaming; natively supported in modern browsers without requiring special protocols or additional libraries

Example: applications use Server-Sent Events to stream live notifications, progress updates, or real-time dashboard data to browsers using HTTP connections with automatic reconnection

Related Terms: event-driven, HTTP, Mercure, WebSocket API

Sources:

• Mozilla Corporation, MDN: "Server-sent events"
• Wikipedia: "Server-Sent Events"

---

SOAP API

Definition: acronym for Simple Object Access Protocol; uses XML-based messaging protocol to exchange structured information between systems, typically over HTTP or HTTPS

Purpose: provides standardized, contract-based communication with built-in error handling and security; common in enterprise environments where formal contracts, transactions, and ACID compliance matter more than simplicity or performance

Key Characteristics:

• WSDL contracts: Web Services Description Language defines the API contract
• XML-only: all requests and responses use XML format
• Protocol-independent: can work over HTTP, SMTP, TCP, or other protocols
• Built-in standards: includes WS-Security, WS-AtomicTransaction, and other enterprise features

Example: a banking system exposes a SOAP API for account transfers with a formal WSDL contract specifying exact XML structure, security requirements, and transaction guarantees

SOAP vs REST:

Aspect	SOAP	REST
Protocol	Strict with rules	Architectural style with guidelines
Format	XML only	JSON, XML, others
Contract	WSDL required	Optional - OpenAPI
Overhead	Higher, verbose XML	Lower, lightweight JSON
Common use	Enterprise, legacy systems	Modern web/mobile APIs

Related Terms: API, error handling, HTTP, REST API, XML

Source: W3C: "SOAP Version 1.2 Part 1: Messaging Framework"

---

STOMP

Definition: acronym for Simple (or Streaming) Text Orientated Messaging Protocol, formerly known as TTMP - Text Orientated Messaging Protocol; text-based protocol for MOM - message-oriented middleware - that provides interoperable communication between clients and message brokers over TCP - Transmission Control Protocol

Purpose: enables messaging integration across different languages and platforms with HTTP-like frame structure; designed for scripting languages to connect to enterprise message brokers

Why this belongs in API Types & Architectures: STOMP is a messaging protocol specification that defines frame format and commands for broker communication, similar to how AMQP and MQTT define messaging patterns; the protocol itself is distinct from broker implementations that support it

Example: web applications use STOMP over WebSocket to send and receive messages from brokers like RabbitMQ or ActiveMQ, enabling bidirectional communication with simple text-based commands

Related Terms: AMQP, HTTP, MQTT, WebSocket API

Sources:

• Geeks for Geeks: "STOMP Protocol"
• STOMP: "The Simple Text Oriented Messaging Protocol"
• Wikipedia: "Streaming Text Oriented Messaging Protocol"

---

webhook API

Definition: pattern where a service sends HTTP POST requests to client-specified URLs when specific events occur, enabling event-driven integrations

Purpose: eliminates constant polling by pushing data to clients only when relevant events happen; commonly used for notifications, integrations, and workflow automation

Example: GitHub sends a webhook POST request to a specified URL whenever someone opens a pull request, allowing CI/CD systems to automatically run tests

Related Terms: API, API endpoint, event-driven, HTTP, MCP server, POST, real-time

Source: Zapier: "What are webhooks?"

---

WebSocket API

Definition: also known as WebSockets; maintains persistent, bidirectional connections between client and server, enabling real-time data exchange without repeated HTTP requests

Purpose: supports live updates, streaming data, and instant communication; essential for chat applications, live dashboards, multiplayer games, and collaborative tools

Example: a stock trading dashboard maintains a WebSocket connection to receive price updates instantly as they occur, rather than polling the server every few seconds

Related Terms: AMQP, API, AsyncAPI, event-driven, HTTP, Mercure, MQTT, real-time, Server-Sent Events, STOMP

Source: Mozilla Corporation, MDN: "The WebSocket API (WebSockets)"

---