API Guide

REST uses HTTP concepts to expose resources through predictable URLs and methods.

How REST APIs Work

REST APIs organize server behavior around resources, not custom remote procedure calls

In a REST-style API, clients interact with nouns such as users, orders, sessions, or invoices. The API exposes URLs that represent those resources, and HTTP methods describe what kind of operation is being requested.

The result is not a strict standard so much as a design style. Good REST APIs feel consistent because their routes, verbs, status codes, and representations line up with the semantics of HTTP.

Last updated: May 11, 2026

Colorful REST API diagram showing collection routes, single-resource routes, and JSON representations.
REST feels coherent when URLs map cleanly to resources and HTTP methods map cleanly to operations on those resources.

The core pattern

  1. A URL identifies a resource or resource collection.
  2. The HTTP method communicates the kind of action being requested.
  3. The request body carries input data when needed.
  4. The response returns a representation of the resource, metadata, or an error.

A practical resource example

A collection URL such as /users might support GET to list users and POST to create one. A single-resource URL such as /users/42 might support GET, PATCH, or DELETE. That split between collection and individual resource URLs is one of the clearest signs that an API is trying to be coherent rather than just exposing random endpoints.

Why idempotency matters

Some operations can be repeated without changing the final result. For example, sending the same DELETE request twice should usually leave the resource deleted either way. This property matters for retries, reliability, and client behavior.

Pagination, errors, and versioning

Real APIs need more than clean nouns. Lists usually need pagination or cursors, errors need machine-readable bodies, and breaking changes need a versioning strategy. These decisions shape the developer experience as much as the route names do.

Many APIs feel frustrating not because they are “not REST enough,” but because their error payloads are vague, their pagination is inconsistent, or their versioning story is unclear.

What makes an API feel RESTful

  • Consistent resource naming such as /users and /users/42.
  • Appropriate use of methods like GET, POST, PUT, PATCH, and DELETE.
  • Useful status codes and error payloads.
  • Stateless requests where the server can understand each request on its own.

Common confusion

  • Not every HTTP API is truly RESTful.
  • REST is a design approach, not a transport separate from HTTP.
  • GraphQL and RPC are different styles, not automatically worse ones.

When REST is not the best fit

If a product needs one highly customized query interface, very fine-grained client control over response shape, or streaming interactions, another style may fit better. The point is not to force every system into REST language. The point is to use the style where it helps clients reason about resources and behavior cleanly.