What is a REST API? Methods, status codes and examples

REST is the most common style for building web APIs. When a mobile app loads your messages, a website shows live prices, or one company’s system sends an order to another’s, there is a good chance a REST API is carrying the data. This guide explains what “REST” means, how a REST request is built, what the HTTP methods and status codes do, and how REST compares with alternatives such as GraphQL.

The idea in one paragraph

A REST API exposes data as resources, each with its own web address (URL), and lets clients work with them using the standard methods of HTTP, the same protocol your browser uses for web pages. A user, an order or a photo each has a URL; reading it is a GET, creating one is a POST, and so on. Responses are usually JSON, a lightweight text format that both people and programs can read. If you are new to APIs in general, start with what is an API.

REST stands for Representational State Transfer, a set of design principles described by Roy Fielding in 2000. In everyday use, “REST API” simply means an HTTP API organised around resources and methods.

Anatomy of a REST request

Every request has four parts:

• Method – what you want to do, such as GET or POST.
• URL – which resource, for example https://api.example.com/v1/orders/1042.
• Headers – extra information, such as the credential (Authorization) and the data format (Content-Type: application/json).
• Body – the data you send, used when creating or updating.

A complete exchange looks like this:

GET /v1/orders/1042 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...

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

{"id": 1042, "status": "shipped", "total": 49.90, "currency": "EUR"}

HTTP methods: the verbs of REST

Method	Purpose	Example
GET	Read a resource or a list	GET /orders?status=open
POST	Create a new resource	POST /orders with the order in the body
PUT	Replace a resource completely	PUT /orders/1042
PATCH	Change some fields	PATCH /orders/1042 with {"status":"cancelled"}
DELETE	Remove a resource	DELETE /orders/1042

GET must never change data; it can be repeated, cached and prefetched safely. PUT and DELETE are designed to be repeatable too: doing them twice leaves the same result as doing them once. POST is not, so sending the same order twice may create two orders, which is why good APIs support an idempotency key for payments and similar actions.

Status codes: how the server answers

• 2xx success: 200 OK, 201 Created, 204 No Content.
• 3xx redirection: the resource is elsewhere, or 304 Not Modified when a cached copy is still valid.
• 4xx client errors: 400 Bad Request for invalid data, 401 Unauthorized for a missing or wrong credential, 403 Forbidden when the credential lacks permission, 404 Not Found, 429 Too Many Requests when you hit a rate limit.
• 5xx server errors: 500, 502, 503 mean the problem is on the provider’s side; retry later.

Reading the status code first saves a lot of debugging. A 401 is a credential problem, a 400 is a problem with what you sent, and a 503 is not your fault at all.

The REST principles that matter in practice

• Stateless requests. Each request carries everything the server needs, including the credential. The server does not remember previous calls, which makes REST APIs easy to scale across many machines.
• Resources, not actions, in URLs. Prefer POST /orders over /createOrder. Nouns in the path, verbs in the method.
• Cacheable responses. Because GET is safe, responses can use the same caching headers as web pages, described in how browser cache works.
• Uniform interface. Once you know one well-designed REST API, the next one feels familiar: the same methods, status codes and JSON.

REST vs GraphQL and other styles

GraphQL uses a single endpoint where the client sends a query describing exactly which fields it wants. It avoids downloading unused data and joins related data in one round trip, which suits complex front ends. The cost is more complex caching and server logic.

gRPC uses compact binary messages and is popular for fast communication between internal services. Webhooks reverse the direction: the provider calls your URL when something happens, instead of you asking repeatedly.

For public APIs, REST remains the default because it works with any programming language, any HTTP tool and the existing web infrastructure.

How to try a REST API yourself

1. Pick a free public API, such as a weather, currency or test API that needs no key.
2. Open its URL in a browser: a GET request shows the JSON response directly.
3. Use a command-line tool, for example curl -i https://api.example.com/v1/items, to see the status code and headers.
4. For APIs that need a credential, add the header the documentation describes. Our guide to API keys and OAuth explains the options.

Frequently asked questions

Is every HTTP API a REST API?

Not strictly. Many APIs called “REST” bend the rules, for example by using only POST. In everyday language the term covers any resource-based HTTP API that returns JSON.

Does REST have to use JSON?

No. REST is independent of the data format; XML and others work. JSON became the default because it is compact and native to JavaScript.

What is an endpoint?

An endpoint is a specific URL and method combination the API supports, such as GET /v1/orders/{id}. API documentation is usually a list of endpoints.

What does API versioning mean?

Providers put a version in the URL (/v1/) or a header so they can change the API without breaking existing clients. When /v2/ appears, /v1/ usually keeps working for a while.

In short: a REST API gives every piece of data its own URL and lets clients read and change it with standard HTTP methods, getting JSON and clear status codes back. Stateless, cacheable requests make REST simple to use and scale, which is why it remains the most common way systems talk to each other on the web.