REST API

Representational State Transfer (REST) is the architectural style for distributed hypermedia systems. It relies on stateless, client-server, cacheable communications protocols (mostly HTTP).

When to Use

• Universal Public Web APIs: Building open, standardized APIs intended for third-party developers, webhooks, and partner integrations.
• HTTP Caching & CDN Optimization: Maximizing cacheability using standard HTTP response headers (Cache-Control, ETag, Last-Modified).
• Resource-Oriented CRUD Operations: Designing intuitive resource hierarchies with standard HTTP semantics (GET, POST, PUT, PATCH, DELETE).
• Stateless Integration: Delivering scalable stateless APIs consumed effortlessly by any HTTP client on any platform.

Quick Start

// Express.js Example
app.get("/users/:id", async (req, res) => {
  const user = await db.find(req.params.id);
  if (!user) return res.status(404).json({ error: "Not Found" });

  // HATEOAS (Hypermedia As The Engine Of Application State) - optional but "True REST"
  res.json({
    ...user,
    links: {
      self: `/users/${user.id}`,
      orders: `/users/${user.id}/orders`,
    },
  });
});

Core Concepts

HTTP Semantics & Idempotency

Different HTTP verbs carry formal idempotency and safety guarantees:

Standardized Error Representations (RFC 7807 / 9457)

Returns machine-readable application/problem+json error responses:

{
  "type": "https://api.example.com/errors/invalid-payment",
  "title": "Invalid Payment Source",
  "status": 422,
  "detail": "The payment card provided has expired.",
  "instance": "/orders/415/payments"
}

Content Negotiation & ETag Caching

Validates whether cached client data is still fresh without resending full payloads:

app.get("/api/v1/users/:id", async (req, res) => {
  const user = await db.getUser(req.params.id);
  const etag = crypto
    .createHash("md5")
    .update(JSON.stringify(user))
    .digest("hex");

  if (req.headers["if-none-match"] === etag) {
    return res.status(304).end(); // Not Modified
  }

  res.setHeader("ETag", etag);
  res.setHeader(
    "Cache-Control",
    "public, max-age=60, stale-while-revalidate=300",
  );
  res.json(user);
});

Common Patterns

Cursor-Based Pagination

Problem: Offset-based pagination (OFFSET 10000) degrades database performance and skips items on concurrent writes.
Solution: Use monotonic cursor identifiers (e.g. created_at + id).

// GET /api/v1/posts?cursor=2026-09-27T10:00:00Z&limit=20
app.get("/api/v1/posts", async (req, res) => {
  const { cursor, limit = 20 } = req.query;
  const posts = await db
    .select()
    .from(postsTable)
    .where(
      cursor ? lt(postsTable.createdAt, new Date(cursor as string)) : undefined,
    )
    .orderBy(desc(postsTable.createdAt))
    .limit(Number(limit) + 1);

  const hasMore = posts.length > Number(limit);
  const data = hasMore ? posts.slice(0, -1) : posts;
  const nextCursor = hasMore
    ? data[data.length - 1].createdAt.toISOString()
    : null;

  res.json({ data, pagination: { hasMore, nextCursor } });
});

Best Practices

Do:

• Use Nouns for Resource URIs: Use /api/v1/orders rather than action verbs like /api/v1/getOrders or /api/v1/createOrder.
• Implement Idempotency Keys on Mutating Requests: Require Idempotency-Key headers on POST/PATCH requests to prevent duplicate charges.
• Document with OpenAPI 3.1: Generate automated Swagger docs, SDK clients, and request validation schemas from OpenAPI specs.
• Implement Monotonic Cursor Pagination: Use limit and starting_after cursor pagination for high-volume datasets.

Don't:

• Return HTTP 200 with { "error": "..." }: Always return correct HTTP status codes (400, 401, 403, 404, 422, 500).
• Break API contracts without versioning: Prefix endpoints with /v1/ or use header versioning when introducing breaking changes.
• Expose raw internal database column names: Map private column names to clean, camelCased JSON fields.

Troubleshooting

References

• Restful API Design (Microsoft)
• Richardson Maturity Model