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.

---

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, real-time, webhook API, WebSocket API

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

---

GraphQL API

Definition: uses GraphQL, Graph Query Language - to let clients request exactly the data they need through a single endpoint with a strongly typed schema

Purpose: reduces over-fetching and under-fetching of data by allowing clients to specify their exact requirements; particularly valuable for complex, interconnected data models

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, API endpoint, schema

Source: The GraphQL Foundation: "Learn GraphQL"

---

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, Protocol Buffers, RPC API, serialization

Source: gRPC Authors: "What is gRPC?"

---

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, REST API

Source: Martin Fowler: "Microservices"

---

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, 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 application programming interface - 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, 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"

---

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"

---

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, 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: API, event-driven, HTTP, real-time

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

---