system-design · intermediate

API Design — Clear Contracts Clients Can Trust

The Central Question

Consider an e-commerce platform running on the APILab platform (apilab.com) where different backend teams implemented endpoints independently:

• Developer A created GET /get_user_by_id?id=42 returning { "usr": "Alice" }.
• Developer B created POST /create_order_now returning HTTP 200 OK with body { "status": "FAIL", "msg": "Out of stock" }.
• Developer C created POST /deleteUser returning HTTP 500 Internal Error when a user ID does not exist.

API Design is the disciplined architectural practice of structuring API resources, HTTP methods, data schemas, error payloads, and pagination mechanisms to create predictable, maintainable software contracts.

This lesson answers one central question: How do engineers design RESTful resource hierarchies, select HTTP methods, structure actionable error schemas, and implement pagination models to build stable, developer-friendly APIs?

The Core Principles of RESTful API Design

The most prevalent API design paradigm for web and mobile backends is REST (Representational State Transfer), which models system functionality around Resources accessed via standard HTTP methods.

flowchart TD
  subgraph Nouns: Identifiable System Resources
    Users["/v1/users (User Accounts)"]
    Orders["/v1/orders (Customer Orders)"]
    Products["/v1/products (Catalog Items)"]
  end
  subgraph Verbs: Standard HTTP Methods
    GET["GET: Read Resource State"]
    POST["POST: Create New Resource"]
    PUT["PUT: Replace Entire Resource"]
    PATCH["PATCH: Update Partial Resource"]
    DELETE["DELETE: Remove Resource"]
  end
  
  Users -->|Exposes| GET
  Users -->|Exposes| POST
  Orders -->|Exposes| PUT
  Orders -->|Exposes| PATCH
  Products -->|Exposes| DELETE

Figure 1: Decoupling resource nouns (URIs) from operation verbs (HTTP methods).

1. Model URIs Around Nouns, Not Verbs

• Poor (RPC Style): POST /api/getOrdersForUser?userId=901
• Poor (Verb in URI): POST /api/createNewOrder
• Good (RESTful Noun): GET /v1/users/901/orders
• Good (RESTful Noun): POST /v1/orders

2. Standardize Plural Noun Conventions

• GET /v1/products $\rightarrow$ Returns a list of products.
• GET /v1/products/prod_88 $\rightarrow$ Returns product prod_88.
• POST /v1/products/prod_88/reviews $\rightarrow$ Creates a new review for product prod_88.

HTTP Method Semantics: Safety and Idempotency

In disciplined API design, every HTTP method conveys strict operational semantics regarding Safety and Idempotency:

flowchart LR
  subgraph Safe & Idempotent (Read Only)
    GET[GET /v1/products]
    HEAD[HEAD /v1/products]
  end
  subgraph Idempotent but Unsafe (Mutates State)
    PUT[PUT /v1/users/42]
    DELETE[DELETE /v1/users/42]
  end
  subgraph Neither Safe nor Idempotent
    POST[POST /v1/orders]
  end

Figure 2: Taxonomy of HTTP methods categorized by Safety and Idempotency properties.

Safety vs. Idempotency Definitions

• Safe Method: An HTTP operation that does not modify system state (read-only). Safe methods can be cached by browsers and CDNs without side effects.
• Idempotent Method: An HTTP operation where executing the request $N$ identical times produces the exact same final server state as executing it once.

HTTP Method Properties Matrix

Structuring Actionable Error Payloads: RFC 7807

A major cause of client integration failure is inconsistent error payloads. One endpoint returns {"err": "missing_field"}, while another returns an un-parsed stack trace.

High-quality API design standardizes all error responses on RFC 7807 (Problem Details for HTTP APIs).

flowchart TB
  ErrResp[HTTP 400 Bad Request Response] --> Type["type: URI pointing to error documentation"]
  ErrResp --> Title["title: Short human summary"]
  ErrResp --> Status["status: HTTP status code (e.g. 400)"]
  ErrResp --> Detail["detail: Specific explanation of this failure"]
  ErrResp --> InvalidParams["invalidParams: Array of specific field errors"]

Figure 3: Anatomy of an RFC 7807 compliant JSON error detail payload.

Production RFC 7807 Error Payload Example

{
  "type": "https://api.apilab.com/errors/validation-error",
  "title": "Invalid Request Parameters",
  "status": 400,
  "detail": "The request payload failed validation against the order schema.",
  "instance": "/v1/orders/err_99102",
  "invalidParams": [
    {
      "name": "items[0].quantity",
      "reason": "Quantity must be an integer between 1 and 100."
    },
    {
      "name": "shippingAddressId",
      "reason": "Address ID 'addr_00' does not exist for this user."
    }
  ]
}

Why Machine-Readable Error Codes Matter

Collection Pagination: Offset vs. Cursor Models

List endpoints (GET /v1/orders) that return thousands of records must implement Pagination. Un-paginated list endpoints cause database memory exhaustion and high latency.

flowchart TB
  subgraph Offset-Based Pagination
    Off1["GET /v1/orders?offset=40&limit=20"] --> OffDB["SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 40"]
    Note1["Issue: Performance degrades to O(N); page drift when items inserted"]
  end
  subgraph Cursor-Based Pagination
    Cur1["GET /v1/orders?cursor=ord_9940&limit=20"] --> CurDB["SELECT * FROM orders WHERE id > 'ord_9940' ORDER BY id LIMIT 20"]
    Note2["Benefit: Fast O(1) indexed lookup; immune to page drift"]
  end

Figure 4: Comparing offset-based SQL scans against indexed cursor-based pagination.

1. Offset-Based Pagination (offset & limit)

• Advantages: Simple to implement in SQL (LIMIT 20 OFFSET 100); allows clients to jump directly to arbitrary page numbers (e.g. Page 5).
• Disadvantages:

2. Cursor-Based Pagination (cursor & limit)

• Advantages:

• Disadvantages: Clients cannot jump to arbitrary page numbers; they must paginate sequentially.

Pagination Comparison Matrix

API Versioning Strategies: Path vs. Header vs. Query Parameters

When shipping breaking changes, backend engineering teams choose between three primary API versioning strategies:

flowchart TD
  Version[API Versioning Strategies] --> Path["1. URI Path Versioning (/v1/orders vs /v2/orders)"]
  Version --> Header["2. Custom Request Header (X-API-Version: 2026-07-24)"]
  Version --> Accept["3. Accept Header Content Negotiation (Accept: application/vnd.company.v2+json)"]
  
  Path --> PathAdv["Explicit in browser & logs; easy edge gateway routing."]
  Header --> HeaderAdv["Clean URIs; allows date-based API evolution (Stripe style)."]
  Accept --> AcceptAdv["Strict REST conformance; complex client configuration."]

Figure 5: Taxonomical comparison of API versioning implementation patterns.

1. URI Path Versioning (/v1/orders)

• Why It Prevails: URI path versioning is explicit, easily inspectable in server access logs, and straightforward to route at edge API gateways.
• Edge Gateway Routing: Ingress proxies like Envoy or Kong inspect the leading /v1 prefix to forward traffic to specific microservice target deployment clusters without parsing payload headers.

Complete Worked Example: Go Cursor-Paginated REST API

Let's inspect a production Go implementation of a RESTful collection handler for the APILab platform (apilab.com) demonstrating cursor-based pagination and RFC 7807 error responses.

package main
import (
	"encoding/base64"
	"encoding/json"
	"net/http"
	"strconv"
)
type Product struct {
	ID    string  json:"id"
	Name  string  json:"name"
	Price float64 json:"price"
}
type PageInfo struct {
	NextCursor  string json:"nextCursor"
	HasNextPage bool   json:"hasNextPage"
}
type PaginatedProductsResponse struct {
	Data     []Product json:"data"
	PageInfo PageInfo  json:"pageInfo"
}
func ProductsHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
limitStr := r.URL.Query().Get("limit")
	limit := 20
	if limitStr != "" {
		if parsedLimit, err := strconv.Atoi(limitStr); err == nil && parsedLimit > 0 && parsedLimit <= 100 {
			limit = parsedLimit
		}
	}
cursor := r.URL.Query().Get("cursor")
	lastID := ""
	if cursor != "" {
		decoded, err := base64.StdEncoding.DecodeString(cursor)
		if err == nil {
			lastID = string(decoded)
		}
	}
// Execute O(1) indexed SQL Query: SELECT id, name, price FROM products WHERE id > $1 ORDER BY id ASC LIMIT $2
	products := fetchProductsFromDB(lastID, limit+1)
hasNext := false
	if len(products) > limit {
		hasNext = true
		products = products[:limit]
	}
nextCursor := ""
	if hasNext && len(products) > 0 {
		lastProduct := products[len(products)-1]
		nextCursor = base64.StdEncoding.EncodeToString([]byte(lastProduct.ID))
	}
res := PaginatedProductsResponse{
		Data: products,
		PageInfo: PageInfo{
			NextCursor:  nextCursor,
			HasNextPage: hasNext,
		},
	}
w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(res)
}
func fetchProductsFromDB(lastID string, limit int) []Product {
	// Database query placeholder...
	return []Product{
		{ID: "prod_101", Name: "Mechanical Keyboard", Price: 129.99},
		{ID: "prod_102", Name: "Wireless Mouse", Price: 59.99},
	}
}

Failure Modes and Engineering Mitigations

What You Should Remember

1. Nouns for URIs, Verbs for HTTP Methods: Name resources with plural nouns (/v1/orders). Use HTTP methods (GET, POST, PUT, DELETE) to express operations.
2. Respect Safety and Idempotency: GET must be safe and read-only. PUT and DELETE must be idempotent. POST is neither safe nor idempotent by default.
3. Standardize on RFC 7807 Error Schemas: Return machine-readable error codes (type, status, detail, invalidParams) so clients can branch logic reliably.
4. Prefer Cursor-Based Pagination for Scale: Use opaque cursor pointers (WHERE id > cursor LIMIT 20) to maintain $O(1)$ database query performance and prevent page drift.
5. Enforce Hard Limits on Collections: Never expose an un-paginated collection endpoint. Set mandatory default and maximum page limits.

Glossary of Terms

Practice Scenario and Self-Assessment

Architecture Scenario

A junior developer proposes the following endpoints:

1. POST /api/getStudentCourses?studentId=42
2. POST /api/deleteEnrollment?enrollmentId=90
3. GET /api/getAllAssignments (returns all 800,000 assignments in one JSON array)

1. Identify the API design flaws in each of the three proposed endpoints.
2. Refactor all three endpoints into a clean RESTful specification adhering to REST resource conventions, proper HTTP verbs, and cursor pagination.

Interactive Self-Assessment

cursor), providing fast O(1) database performance and preventing page drift during active writes.">It uses indexed range scans for O(1) database performance and eliminates page drift during concurrent writes.

It allows clients to jump directly to arbitrary page numbers (such as Page 500) faster.

It automatically compresses HTTP JSON payloads using Gzip compression.

It eliminates the need for HTTP status codes on collection endpoints.

The machine-readable 'type' URI code indicating the specific error category.

The human-readable 'detail' text string explaining the error.

The generic HTTP 400 status code alone.

The 'instance' request trace ID assigned to the execution.

What to Learn Next

• API Gateway — Edge Entry for Microservices: Learn how edge gateways enforce authentication, routing, and rate limits.
• REST vs RPC — Wire Protocol Trade-offs: Compare REST JSON vs gRPC Protobuf binary communication.
• REST vs GraphQL — Query Flexibility vs Over-Fetching: Explore GraphQL query flexibilities and DataLoader mechanics.

Track: Software Design and Architecture

Next: Distributed Rate Limiting — Shared Quotas Across Many Pods

By Shubham Jain

All articles · Study paths

Shubham Jain · Learning Lab