API Design

Google API Design Guide

Opinionated REST and gRPC design rules: resource-oriented URIs, plural nouns, pagination, errors.

Microsoft REST API Guidelines

Cross-company REST consistency rules (nouns, verbs, versioning, errors).

Stripe API Versioning Policy

Backwards-compatible evolution strategy and pinned versions for API consumers.

Backends for Frontends (BFF)

An architecture pattern that gives each frontend client its own tailored backend service, instead of forcing web, mobile, and other clients to share one general-purpose API.

API Gateway Pattern

An architecture pattern that places a single entry point in front of backend services to handle routing, authentication, rate limiting, and other cross-cutting concerns.

Richardson Maturity Model

A four-level model for grading how fully an HTTP API embraces REST, from RPC-style endpoints up to hypermedia controls (HATEOAS).

OpenAPI Specification Best Practices

Guidance for writing accurate, machine-readable OpenAPI documents that describe HTTP APIs and drive docs, client SDKs, mocks, and contract tests.

GraphQL API Best Practices

Practical guidance for designing GraphQL schemas and servers: typed schemas, pagination, error handling, query cost limits, and avoiding the N+1 problem.

gRPC Best Practices

Guidance for building high-performance gRPC services with Protocol Buffers: service design, streaming, deadlines, error codes, and backward-compatible schema evolution.

API-First Design

An approach that treats the API contract as a product designed before implementation, so teams agree on the interface, then build clients and servers in parallel.

Idempotency Keys

A pattern where clients send a unique key with unsafe requests so the server can safely retry without applying the same operation twice, preventing duplicate charges or records.

API Rate Limiting

Controlling how many requests a client can make in a time window to protect API capacity, ensure fair use, and defend against abuse, using algorithms like token bucket.

API Pagination Best Practices

Techniques for returning large result sets in pages without breaking under concurrent writes: offset, cursor (keyset), and page-token pagination, with stable ordering.

Webhook Best Practices

Guidance for sending and receiving reliable webhooks: signature verification, idempotent handlers, retries with backoff, and fast acknowledgement of events.

AsyncAPI Specification

A standard, machine-readable format for describing event-driven and message-based APIs across protocols like Kafka, MQTT, and AMQP, analogous to OpenAPI for REST.

Problem Details for HTTP APIs (RFC 9457)

An IETF standard JSON format for machine-readable HTTP error responses, defining fields like type, title, status, detail, and instance for consistent error handling.

API Backward Compatibility

Evolving an API without breaking existing clients by making only additive changes, versioning breaking changes, and deprecating fields gracefully over time.

JSON:API Specification

A convention for building JSON APIs that standardizes resource structure, relationships, pagination, filtering, and sparse fieldsets to reduce bikeshedding and over-fetching.

Patterns24

Anti-Corruption Layer

Create a translation layer between new and legacy systems to prevent legacy concepts from leaking into new code

Backend for Frontend (BFF)

Create separate backend services tailored to each frontend's needs

Front Controller

Channels all incoming requests through a single handler that centralizes cross-cutting concerns like routing, authentication, and logging before dispatching to handlers.

API Gateway

A single entry point that routes, aggregates, and secures client requests across many backend microservices.

API Composition

Implements a query that spans multiple services by invoking each owner service and joining the results in memory.

Aggregator

A component that invokes multiple services and combines their responses into a single consolidated result for the caller.

Gateway Aggregation

Uses a gateway to combine multiple backend requests into one, so clients make a single call instead of many.

Gateway Offloading

Moves shared cross-cutting functionality such as TLS, auth, and rate limiting out of services and into a gateway.

Gateway Routing

Routes client requests to the correct backend service through a single endpoint using request attributes such as path or host.

Throttling

Control the consumption of resources by an instance, tenant, or service so a system stays within capacity under load.

Rate Limiting

Constrain the rate of operations against a service or resource to stay within quotas and avoid throttling or overload.

Message Router

Consumes a message and redirects it to a different channel based on conditions, decoupling producers from the decision of where messages should go.

Content-Based Router

Routes each message to a destination channel chosen by inspecting the message's content, so the payload itself determines where it is delivered.

Message Translator

Converts a message from one data format or schema to another so systems with incompatible representations can communicate.

Normalizer

Translates messages arriving in many different formats into a single common format so downstream components handle one canonical representation.

Request-Reply

Lets a requestor send a message and receive a corresponding response over messaging, combining two one-way channels into a logical two-way exchange.

Rate Limiter

Caps how many requests a client or system may make in a time window, protecting services from overload, abuse, and runaway cost.

Idempotency Key

Attaches a unique key to a request so the server can detect and de-duplicate retries, making non-idempotent operations safe to repeat.

Pagination

Splits a large result set into smaller pages so APIs and UIs can return and traverse data incrementally instead of loading everything at once.

HATEOAS

Hypermedia as the Engine of Application State: REST responses include links describing available actions, letting clients navigate the API by following links.

Idempotency Key

A client-supplied unique key lets a server detect and dedupe retried requests, so repeated submissions produce the same result exactly once.

API Versioning

Strategies for evolving an API without breaking existing clients, by exposing multiple versions through URLs, headers, or media types.

Webhook

A server pushes event notifications to a client-registered HTTP endpoint as events occur, replacing inefficient polling with real-time callbacks.

Token Bucket (Rate Limiting)

A rate-limiting algorithm where requests consume tokens refilled at a steady rate, allowing controlled bursts while capping the long-run request rate.

Anti-Patterns19

Shared Database Integration

Multiple services directly sharing the same database tables

Stovepipe System

Independently built, siloed systems that duplicate capabilities and cannot interoperate because each was designed in isolation without shared standards.

Swiss Army Knife

An interface or component with so many options and overloads that it tries to cover every use case, becoming hard to learn, misuse-prone, and impossible to evolve.

Boolean Trap

Function parameters that take a bare boolean force readers to decode opaque true/false call sites, hiding intent and inviting wrong arguments.

Long Parameter List

A function signature with too many parameters, making calls error-prone, hard to read, and a sign of poorly grouped or missing abstractions.

Temporal Coupling

Methods that must be called in a specific hidden order, where calling them out of sequence silently breaks state with no compiler protection.

Sequential Coupling

A class designed so its methods must be invoked in a rigid sequence, with the ordering enforced only by convention rather than by the API itself.

Chatty I/O

Making many small, fine-grained remote or storage calls where a few coarse-grained calls would do, multiplying latency and overhead per operation.

N+1 Network Calls

Fetching a list, then making one additional remote call per item to enrich it, so a single logical operation fans out into N+1 dependency calls.

Overly Permissive CORS

Configuring Cross-Origin Resource Sharing to allow any origin (or reflecting any origin with credentials), exposing authenticated APIs to malicious sites.

Missing Input Validation

Accepting and processing external input without checking its type, range, format, or size, opening the door to injection, corruption, and crashes.

Mass Assignment

Binding incoming request data directly onto domain objects, letting attackers set fields like isAdmin or accountBalance that were never meant to be writable.

Chatty API

An API design that forces clients to make many small round trips to complete one task, harming latency, scalability, and battery life.

Breaking Changes Without Versioning

Changing an API's contract in place without versioning or deprecation, silently breaking existing clients and eroding trust.

Inconsistent API Naming and Conventions

An API where naming, casing, pluralization, error formats, and conventions vary across endpoints, raising the learning curve and integration errors.

Overfetching and Underfetching

Endpoints that return too much data or too little, forcing clients to waste bandwidth or make extra calls to assemble what they need.

Ignoring Idempotency

Designing write operations that cause duplicate effects when retried, so network blips and client retries create double charges or duplicate records.

Missing Pagination (Unbounded Result Sets)

Collection endpoints that return all records at once with no pagination, causing huge payloads, slow queries, and out-of-memory failures as data grows.

Leaky API Abstraction

An API that exposes internal database schemas, implementation details, or storage structures, coupling clients to internals and blocking safe evolution.

Tutorials16

Building a GraphQL API from REST Endpoints

Transform your REST API into a GraphQL server with Apollo

How to deploy a serverless REST API on AWS Lambda

Build and deploy a production REST API using AWS Lambda and API Gateway with infrastructure as code.

How to build an HTTP API with Azure Functions

Create and deploy a serverless HTTP-triggered API on Azure Functions using the Azure CLI and a consumption plan.

How to build a REST API with Amazon API Gateway

Configure Amazon API Gateway routes, stages, and authorizers to expose backend services as a managed REST API.

How to deploy a Python function on Google Cloud Functions

Write and deploy an HTTP-triggered Python function on Google Cloud Functions (2nd gen) with the gcloud CLI.

How to Secure an API with JWT Authentication

Issue signed JWT access tokens, validate them on every request, and refresh them safely without leaking long-lived credentials.

How to Add Rate Limiting to an API

Protect an API with token-bucket rate limiting, return standard rate-limit headers, and share limits across instances with Redis.

How to Build a REST API with Best Practices

Design resource-oriented routes, use correct status codes, validate input, handle errors consistently, and version your REST API.

How to Document an API with OpenAPI

Write an OpenAPI specification, serve interactive docs, validate requests against the schema, and generate client code.

How to Build a GraphQL Server

Define a schema, write resolvers, solve the N+1 problem with batching, and add error handling and depth limits to a GraphQL API.

How to Build a gRPC Service

Define a service in Protocol Buffers, generate code, implement unary and streaming methods, and call the service from a client.

How to Implement Secure Webhooks

Send and receive webhooks with HMAC signatures, idempotency keys, retries with backoff, and replay protection.

How to Version an API Without Breaking Clients

Choose a versioning scheme, evolve schemas with additive changes, deprecate old versions gracefully, and communicate changes to clients.

How to Add Cursor-Based Pagination to a REST API

Replace offset pagination with stable cursor pagination, return navigation links, and keep results consistent under concurrent writes.

How to build an LLM app with function calling (tools)

Give an LLM the ability to call your functions, so it can fetch data and take actions instead of only producing text.

How to build a Model Context Protocol (MCP) server

Build an MCP server that exposes tools and resources to AI assistants over a standard protocol.

Blueprints10

REST to GraphQL Migration Blueprint

Guide for transitioning REST APIs to GraphQL architecture

EJB to REST Services Blueprint

Replace remote EJB interfaces with HTTP REST services to decouple clients from RMI and enable language-agnostic integration.

SOAP to REST API Modernization Blueprint

Modernize WSDL-based SOAP web services to REST APIs with OpenAPI contracts, JSON payloads, and OAuth 2.0 security.

REST API to GraphQL Federation Blueprint

Migrate a sprawling set of REST endpoints to a federated GraphQL graph so clients fetch exactly what they need from one typed endpoint.

REST to gRPC for Internal Services Blueprint

Replace JSON-over-HTTP calls between internal microservices with gRPC and Protocol Buffers for lower latency and strongly typed contracts.

Monolithic API to API Gateway Blueprint

Front a monolithic API with an API gateway to centralize auth, rate limiting, routing, and observability before decomposing services.

Ad-Hoc REST Versioning to API-First Contracts Blueprint

Move from unmanaged REST API changes to an API-first workflow with OpenAPI contracts, contract testing, and a backward-compatibility policy.

REST Polling to GraphQL Subscriptions Blueprint

Replace client REST polling for fresh data with real-time GraphQL subscriptions over WebSockets for push updates and lower load.

Oracle Forms to Web Application Blueprint

Modernize Oracle Forms and Reports applications into a modern web app with a REST API over the existing Oracle Database.