REST API Explained: How It Works With a Practical Example

An API lets two pieces of software exchange information or request actions through a defined interface. REST is an architectural style for distributed systems; it is not a programming language, a protocol, or a synonym for JSON. When an API uses HTTP and organizes its interface around resources while following REST ideas, it is commonly described as a REST or RESTful API.

That distinction matters because it is easier to learn APIs when you understand what happens between client and server instead of memorizing a list of recipes. If those two parts of an application are still unclear, start with our guide to frontend and backend differences.

What is a REST API in simple terms?

Imagine an application that displays a store's inventory. Its user interface needs to list products, retrieve one product, register an order, or update a quantity. Rather than connecting directly to the database, the application can communicate with a service through an API.

A request might target a resource like this:

GET /products/42

The server interprets the request and sends a response. If it succeeds, that response can include product data and an HTTP status code describing the result.

The API defines what the client may ask for, how it should ask, and what responses it can expect. The internal implementation—database, language, services, and business rules—can evolve without forcing the client to know those details, provided the interface contract remains compatible.

API, REST, and RESTful are not the same thing

An API is a broad concept: an interface through which software communicates with other software.

REST, or Representational State Transfer, is the architectural style Roy Fielding described for distributed hypermedia systems. Its constraints include client-server separation, stateless communication, cacheability, a uniform interface, and a layered system. Code-on-demand is optional.

RESTful is commonly used to describe a system that applies those constraints. In practice, many APIs are called “REST” because they use HTTP, resources, and methods such as GET or POST even when they do not implement every aspect of Fielding's model. It is therefore better to treat “RESTful” as an architectural description rather than an automatic label.

How a REST API works between client and server

A basic HTTP interaction has four easy-to-recognize parts:

1. Method: expresses the semantics of the request, such as GET, POST, PUT, PATCH, or DELETE.
2. Target URI or URL: identifies the resource the request addresses.
3. Headers and, when appropriate, content: can carry authentication information, representation types, preferences, and submitted data.
4. Response: includes a status code, headers, and, when appropriate, a representation of the result.

For example, an application might send:

GET /api/products/42 HTTP/1.1
Host: example.test
Accept: application/json

And receive:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "USB Keyboard",
  "available": true
}

This is a fictional example for learning purposes; it does not represent a public Crezendo API.

Resources and endpoints

REST primarily focuses on resources: products, orders, users, documents, or other entities an application needs to represent and manipulate.

A consistent interface might use paths such as:

/products
/products/42
/orders
/orders/830

API documentation often uses the word endpoint for a specific point of interaction, commonly combining a route with an operation. For example, GET /products/42 and DELETE /products/42 target the same URI but have different semantics.

You do not need to fill routes with verbs such as /getProduct or /deleteProduct. HTTP already defines methods with specific semantics, and a resource-oriented API is often easier to understand when routes represent nouns.

HTTP methods: GET, POST, PUT, PATCH, and DELETE

HTTP methods are not arbitrary labels. HTTP defines their semantics and properties such as safety and idempotency.

A common beginner shortcut is POST = create and PUT = edit. That can be a useful first mental model, but it does not replace HTTP semantics. Each API still needs to document what a specific operation accepts and produces.

JSON is common, but REST does not require it

JSON is a lightweight, text-based, language-independent data interchange format. It is extremely common in web APIs because applications can produce and consume it easily, but REST does not require JSON.

A representation can be JSON, HTML, XML, text, an image, or another format appropriate to the resource and understood by both sides. HTTP can negotiate and declare representation types through headers such as Accept and Content-Type.

Example JSON:

{
  "id": 830,
  "status": "pending",
  "total": 24.50
}

REST does not define that structure; the API contract does.

HTTP status codes beginners should recognize

The status code summarizes the outcome of an HTTP request. Useful ones to recognize early include:

• 200 OK: the request succeeded and the response contains the appropriate result.
• 201 Created: the request resulted in one or more resources being created.
• 204 No Content: the request succeeded and no response content is sent.
• 400 Bad Request: the server considers the request invalid because of a client-side problem.
• 401 Unauthorized: valid authentication credentials are missing for the target resource.
• 403 Forbidden: the server understood the request but refuses to authorize it.
• 404 Not Found: the server found no current representation of the target resource, or does not wish to disclose that one exists.
• 409 Conflict: the request conflicts with the current state of the target resource.
• 500 Internal Server Error: the server encountered an unexpected condition that prevented it from fulfilling the request.

Avoid returning 200 for every outcome and putting an error only inside the JSON body. Correct HTTP semantics make it easier for clients, proxies, observability systems, and testing tools to understand what happened.

Practical example: an inventory API

Suppose a fictional store exposes these operations:

GET    /products
GET    /products/42
POST   /orders
PATCH  /orders/830
DELETE /orders/830

1. Retrieve a product

GET /products/42

Possible response:

{
  "id": 42,
  "name": "USB Keyboard",
  "stock": 7
}

2. Create an order

POST /orders
Content-Type: application/json

{
  "product_id": 42,
  "quantity": 2
}

If the server creates the order, it can return 201 Created, a Location header identifying the new resource, and a representation of that order.

3. Modify part of the order

PATCH /orders/830
Content-Type: application/json

{
  "quantity": 3
}

The server must document the patch format it accepts. PATCH does not mean that any arbitrary JSON object is automatically a valid patch document.

This small exercise already lets you practice routes, methods, request bodies, content types, status codes, and error handling without depending on one framework.

What “stateless” means in REST

The stateless constraint means each client request must contain the information necessary for the server to understand it; the server cannot depend on session context stored between requests in order to interpret the message.

That does not mean the server stores no state. A database can persist users, orders, permissions, and any other application state. REST constrains the interaction session state the server would otherwise need to remember between one request and the next.

It also does not automatically mean “faster.” Architectural constraints create particular tradeoffs and properties; actual performance depends on the design, infrastructure, caching, database, workload, and many other factors.

REST is not simply HTTP + JSON

Avoid these misleading equivalences:

• REST = HTTP: REST is an architectural style; HTTP is a protocol with defined semantics.
• REST = JSON: JSON is only one possible representation format.
• REST = CRUD: create, read, update, and delete are useful operations, but they do not define REST by themselves.
• endpoint = database table: an API does not have to expose the database structure directly.
• stateless = no persistent data: the server can persist resource state without keeping interaction session context between requests.

Understanding those differences makes real API documentation much easier to read and helps you recognize inconsistent designs.

Common mistakes when designing or consuming REST APIs

1. Ignoring status codes: a robust client should not assume every response is successful.
2. Confusing authentication and authorization: proving who you are does not grant permission to every operation.
3. Putting secrets in URLs: credentials and tokens need appropriate mechanisms; they should not casually appear in parameters that can end up in histories or logs.
4. Failing to validate input: servers should treat client input as untrusted.
5. Breaking the contract without a migration strategy: changing fields or meanings can break existing consumers.
6. Choosing methods only for convenience: semantics, idempotency, caching, and intermediary behavior depend on those choices.
7. Assuming valid JSON means the operation succeeded: clients still need to examine HTTP status and business rules.

How to practice without memorizing definitions

A useful beginner path is to build a minimal API with four or five operations and test it with curl, a browser where appropriate, or an API client. Then add validation, authentication, pagination, filtering, and consistent error handling.

For every operation, try to answer:

• What resource am I representing?
• Which method best expresses the intention?
• What data does the request accept?
• What status and representation does it return on success?
• What errors can occur?
• Is the operation safe or idempotent according to HTTP?
• What must a client know to use it without understanding the internal implementation?

That reasoning is more valuable than memorizing that “GET reads and POST creates.”

Technical sources

• Roy Fielding, Chapter 5 of the dissertation that defines REST: REST's architectural constraints and induced properties.
• RFC 9110 — HTTP Semantics: current HTTP method, status-code, and semantic definitions.
• RFC 5789 — PATCH Method for HTTP: definition of the PATCH method.
• RFC 8259 — JSON: specification of the JSON data-interchange format.

If your team is considering practical technical training or needs help defining a learning path, contact Crezendo and explain the skills you want to develop.