What is a REST API?

A REST API is a web API that follows a specific style: every URL identifies a thing (a resource), and you act on those things using the standard HTTP methods. If you have ever calledGET /users to list users orPOST /users to create one, you have used a REST API.

The acronym stands for Representational State Transfer. Roy Fielding coined it in his 2000 PhD dissertation as a description of how the web actually worked. It is less a strict specification and more a set of principles. Most production APIs today are "RESTish": they take the parts that matter and ignore the parts that do not.

The shape of a REST API

Three things define a REST API in practice:

• Resources are nouns. Each URL points at a thing:/users is the collection,/users/123 is one user. URLs do not contain verbs, so no/getUser?id=123 or/createUser.
• Methods are verbs. The HTTP method tells the server what to do with the resource:GET to read,POST to create,PATCH orPUT to update,DELETE to remove.
• State lives on the client. Each request stands alone. The server does not remember that you called something five minutes ago. If you need to "log in", you send your credentials (a bearer token) on every call; the server does not keep a session.

A real request

Here is what calling a REST API actually looks like over the wire. This request reads the list of users:

GET /public/v2/users HTTP/1.1
Host: gorest.co.in
Accept: application/json

And here is the response:

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

[
  { "id": 1, "name": "Avani Iyer", "email": "avani@example.com", "status": "active" }
]

Three lines on the request, two-plus-body on the response. The response status code (200) tells your code immediately whether to trust the body or not. The body itself is JSON, the de-facto serialization for modern APIs.

The HTTP methods, in detail

Each method has expected behaviour:

• GET reads. Should not have side effects. Safe to retry, safe to cache.
• POST creates a new resource. Returns 201 with the new row's id. Each call typically creates a new row, so retries are not safe.
• PATCH applies a partial update. Send only the fields that change.
• PUT replaces the entire resource. Missing fields are reset, not preserved.
• DELETE removes the resource. Returns 204 with no body.

These are conventions, not laws; the API designer decides what each method does. A well-designed REST API follows them so client developers can guess correctly.

Idempotency

A request is idempotent if calling it twice has the same effect as calling it once.GET,PUT,DELETE, andHEAD are idempotent;POST is not. This matters because retries are normal: a network blip, a 503, a queue worker that died mid-task. Idempotent calls are safe to retry. Non-idempotent calls need extra care, usually a unique idempotency key sent by the client so the server can dedupe.

Statelessness

The "stateless" in REST means the server does not keep client state between requests. Every request carries everything the server needs: who you are (token), what you want (URL + method), and the data (body if applicable). The server might cache things or have a database; that is its own state, not yours.

This is why bearer-token auth is so common. The token is the entire session: send it on every call, the server looks it up, and you are identified. There is no "log in once and stay logged in" handshake; the server treats every request as fresh.

What about HATEOAS?

Strict REST includes one more idea: HATEOAS (Hypertext as the Engine of Application State). The response includes links that tell the client what to do next: "here is the user, here is the link to update them, here is the link to their posts". Almost no APIs in the wild do this. Most production APIs document their endpoints out-of-band (Swagger, OpenAPI, or just docs pages) and skip embedding hyperlinks in responses.

When you would not use REST

If your data is fundamentally a graph (think social-network friendships, e-commerce product attributes), GraphQL is often a better fit because it lets one request fetch related data in one shot. If your interactions are real-time (chat, multiplayer games), WebSockets or server-sent events are usually right. If you need typed, schema-validated, high-performance internal RPC,gRPC beats REST. For everything else (public APIs, mobile-app backends, single-page apps fetching data), REST is the default and probably will be for a long time.

Try one

The easiest way to feel REST is to call one. Open a terminal and run:

curl https://gorest.co.in/public/v2/users

You will get back a JSON list of users. That is a REST API in action.