Scrapeless Wiki

What Is a REST API? – Definition and How It Works

Informational P1 what is a rest api
Overlaps a live page. A published page already targets this keyword: https://www.scrapeless.com/en/blog/rest-api. Publishing both risks cannibalisation — decide before this goes live.

Learn what a REST API is, how resources, methods and status codes fit together, what statelessness means in practice, and how REST differs from RPC.

A REST API exposes data as addressable resources manipulated with standard HTTP methods. It is the dominant style for web APIs because it reuses machinery the web already has rather than inventing a parallel one.

1. What Is a REST API?

REST — Representational State Transfer — is an architectural style, not a protocol or a specification.

  • Key idea: everything is a resource with a URL, acted on by standard HTTP methods.
  • Mechanism: the URL names what; the method says what to do; the status code reports the result.
  • Goal: a uniform, predictable interface that any HTTP client already understands.

Example

GET    /api/v1/products          → list products
GET    /api/v1/products/1234     → one product
POST   /api/v1/products          → create one
PATCH  /api/v1/products/1234     → update fields
DELETE /api/v1/products/1234     → remove it

The pattern is guessable, which is much of the point. Knowing one endpoint tells you the shape of the rest.

2. Methods and Their Contracts

Method Purpose Safe Idempotent
GET Retrieve Yes Yes
POST Create, or non-idempotent action No No
PUT Replace entirely No Yes
PATCH Update partially No Not necessarily
DELETE Remove No Yes

Safe means it changes nothing. Idempotent means repeating it has the same effect as doing it once.

These are contracts, not suggestions. A GET that mutates state breaks caches, prefetchers and crawlers in ways that are painful to debug. And idempotency is what makes retrying safe: a failed DELETE can be retried, a failed POST may create a duplicate.

3. Status Codes

Range Meaning Common
2xx Success 200 OK, 201 Created, 204 No Content
3xx Redirection 301, 304 Not Modified
4xx Client error 400, 401, 403, 404, 409, 422, 429
5xx Server error 500, 502, 503

The distinction that matters for clients: 4xx will not be fixed by retrying — the request itself is wrong. 5xx and 429 may well be — retry with backoff.

4. Statelessness

Every request carries everything needed to process it. The server keeps no client session between calls.

The practical consequences are the reason REST scales:

  • Any server instance can handle any request, so load balancing is trivial.
  • A restarted server loses no client context.
  • Horizontal scaling needs no session replication.

Authentication is therefore sent per request — a bearer token or API key on every call, not a server-side session established once.

5. Pagination, Filtering, Versioning

Real APIs need more than five verbs:

  • Pagination. Offset (?page=2&limit=50) is simple and drifts when data changes underneath. Cursor (?after=abc123) is stable and cannot jump to an arbitrary page.
  • Filtering and sorting via query parameters: ?status=active&sort=-created_at.
  • Field selection to trim payloads: ?fields=id,name,price.
  • Versioning, usually in the path (/v1/) or a header. Its purpose is the promise that /v1/ keeps behaving as documented — which is the single largest advantage an API has over scraping.

6. REST vs. RPC vs. GraphQL

RPC exposes actions: /getProduct, /createProduct. Natural for operations that are not really CRUD, but every endpoint must be learned individually.

GraphQL exposes one endpoint and a query language, letting the client request exactly the fields it wants across related objects in one round trip — at the cost of caching being harder and query cost being the server's problem.

REST sits between: uniform and cacheable, but prone to over-fetching (returning fields you did not need) and under-fetching (needing three calls to assemble one view).

Most real APIs are not purely any of these. A REST API with a few RPC-shaped action endpoints — /orders/123/refund — is normal and sensible, because some operations simply are not resources.

7. Real-World Examples

  • A payments API where POST creates a charge and idempotency keys prevent double-charging on retry.
  • A catalogue API paginated by cursor because products are added constantly and offsets skip records.
  • A 409 Conflict returned when two clients update the same record, letting the loser retry deliberately.
  • A /v1/ endpoint still serving traffic years after /v2/ shipped, because the version was a promise.
  • A page's internal REST endpoint found in the Network tab, returning cleaner data than the rendered HTML ever would.

8. Summary

A REST API models data as resources at URLs, acted on with standard HTTP methods, reporting outcomes through status codes, with no server-side session between requests. Safety and idempotency are contracts that determine what a client may safely retry.

Its strengths are predictability, cacheability and reuse of existing HTTP infrastructure; its weaknesses are over- and under-fetching, which GraphQL exists to address. In practice, most APIs are REST with pragmatic exceptions — and for anyone extracting data, the internal REST endpoint behind a page is almost always a better target than the page itself.