Glossary

REST API: how this architectural style for HTTP interfaces works

REST is neither a JSON format nor a ready-made library. It describes principles that govern communication between a client and server.

Short definition

REST is a specific style for designing distributed interfaces.

REST stands for Representational State Transfer. It describes a set of constraints for distributed applications: separation of client and server, a uniform interface, stateless communication, and working with representations of resources. It does not prescribe a single library or mandatory data format.

A client does not work directly with a database table or an internal server object. It calls a resource, such as an order, and receives its representation—often JSON. REST is narrower than API: an API may be local, RPC-based, or asynchronous, while REST describes a specific style of web communication.

Use cases

When a REST API makes sense

REST APIs are well suited to stable interfaces built around identifiable data and application states.

product catalogues, customers, and user accounts
orders, stock availability, and online-store administration
a backend for a web or mobile client
partner integrations with a shared HTTP contract
export or long-running jobs modelled as separate resources

Practical example

Managing an order and catalogue

The administration interface loads an order with GET /orders/4812. The fulfilment queue uses GET /orders?status=paid&sort=createdAt&limit=50&cursor=…, avoiding downloading every order at once. It can change the address through PATCH /orders/4812 using a predefined change format.

If the order has already shipped and a rule prohibits the change, the API returns a documented state conflict rather than a generic success. Creating a new order with POST /orders also needs an idempotency key: if the connection is lost, the client cannot know whether the first request succeeded.

How it works

Resource, representation, and HTTP request

A simplified interaction with a REST interface works as follows:

Resource A URL identifies a concept, such as /orders/4812; it does not have to correspond to a single database row.
Request The client sends a method, URL, headers, and, where needed, a body containing the change.
Rules The server verifies permissions, inputs, and the business rules governing the change.
Representation The response returns an HTTP status and the current state of the resource or an error description.
Next page For collections, the client continues using the documented cursor, filter, and sort order.

Key characteristics

The semantics a client needs to know

The greatest benefit of REST is not the wording of a URL, but the predictable behaviour of the contract.

URLs and a uniform interface

A collection might be /orders and a specific order /orders/4812. The goal is not to ban every verb from a path mechanically, but to give the client readable semantics.

HTTP methods

GET reads and should not change business state. POST typically creates something or starts processing. PUT sets the target state, PATCH describes a partial change, and DELETE requests removal.

Statuses and errors

201 usually indicates a created resource, 202 accepted asynchronous work, and 204 success without a body. Errors require a consistent agreement on 4xx and 5xx statuses and the response format.

Statelessness and caching

Each request carries the information needed to understand it. This does not prohibit a database; it concerns the state of the communication. Appropriately marked responses can be cached.

Benefits and limitations

REST is not a template for every business action

Benefits

uses familiar HTTP methods, statuses, headers, and tooling
consistent resources and methods reduce the number of exceptions a client must handle
separates client and server and supports multiple types of clients
stateless requests make retries and horizontal scaling easier

Common mistakes

using GET to change state
always returning HTTP 200 with a vague success string in JSON
removing old fields without a compatibility period
interpreting stateless as a ban on authentication or databases

Scope

Not every JSON API is truly RESTful.

An API with POST /doSomething and the same status every time may work, but it does not make good use of HTTP semantics. The opposite mistake is to create unnatural URLs merely to earn the REST label. For a long-running operation, creating a job resource and returning 202 is often clearer than pretending it completed immediately.

An idempotent HTTP method alone does not prevent duplicate business operations that span multiple systems. Creating an order or shipment requires protection designed for that specific operation.

What to consider

Rules for a clear HTTP interface

The contract should cover exceptional and operational states, not only the happy path.

GET without mutating business state
unambiguous statuses, a machine-readable error type, and a correlation ID
a maximum limit and stable sorting for collections
backward-compatible changes or a clear migration plan
secure token transmission outside the query string

Common questions

What REST means in practice

Are REST APIs and HTTP APIs the same?

No. An HTTP API may use HTTP without following REST constraints. REST is one architectural style with a uniform interface, resources, and other principles.

Is every JSON API a REST API?

No. JSON is a data format. REST is defined by the semantics of resources, methods, states, and communication, not by the response file extension.

What is the difference between PUT and PATCH?

PUT sets the representation of the target resource, while PATCH describes a partial change. The PATCH contract must define exactly how to interpret that change; PATCH is not automatically idempotent.

Does a REST API have to put its version in the URL?

No. REST does not specify where a version belongs. Avoiding incompatible changes and documenting the transition in advance matter more.

How I use REST APIs in practice

I design APIs with integration operations in mind.

For integration services, I address data contracts, error states, request retries, and synchronisation traceability as well as endpoints.

How I work with APIs and integrations Discuss your project without obligation