Skip to content

REST API

A REST API is a web API organized around resources and standard HTTP concepts such as URLs, request methods, headers, and status codes.

A REST API is an API designed around resources and standard web technologies such as HTTP methods, URLs, headers, and status codes.

REST is a common approach for web APIs, though individual implementations vary considerably.

What It Looks Like

A REST-style API might expose resources such as:

GET /products
GET /products/123
POST /products
PATCH /products/123
DELETE /products/123

The API Endpoint identifies the resource.

The HTTP Method describes what should happen to it.

REST API vs. API

API is the broad concept.

REST is one approach to designing an API.

Other approaches include:

  • GraphQL
  • RPC systems
  • SOAP
  • Event-driven interfaces
  • Platform-specific protocols

So:

Every REST API is an API.

but:

Not every API is REST.

REST and JSON

REST APIs commonly exchange JSON, but REST does not inherently require JSON.

A response could theoretically use another representation.

JSON became especially common because it is lightweight and widely supported by web-development tools.

Real-World APIs

GitHub provides a substantial production example through its REST API documentation.

Its API exposes endpoints, Authentication, Rate Limits, Pagination, and API Versioning, demonstrating how those glossary concepts work together in a real service.

Why It Matters

REST APIs are common across:

  • CMS platforms
  • CRMs
  • Ecommerce
  • Booking systems
  • Analytics
  • Payments
  • Government data
  • SaaS tools

Your existing Content API, for example, may be exposed through REST-style operations depending on the CMS.

Common Problems

Common problems include:

  • Calling every HTTP API “REST” regardless of design
  • Hardcoding assumptions about URL structures
  • Ignoring Pagination
  • Ignoring Rate Limits
  • Treating API responses as permanently stable
  • Poor error handling
  • Authentication credentials stored insecurely

How to Improve

Use the provider's documentation rather than relying on generic REST conventions.

The conventions make APIs easier to understand, but the published contract defines what an individual API actually supports.