What is a REST API? A quick guide to how they work

Introduction

Almost every API you touch today is called a "REST API," but the label gets slapped on anything that talks over HTTP, even though REST describes something more specific: an API built around a particular set of design rules for how a client and a server exchange data.

Here's what a REST API actually is, the six constraints that define REST, and a real request and response instead of an abstract example. You'll also get a straight answer on how the terms "REST API," "API," and "RESTful API" relate to each other, plus a look at REST APIs built specifically for browser automation and web scraping, since that's a use case none of the standard explainers cover.

What is a REST API?

A REST API is an API built to follow REST (representational state transfer), an architectural style of constraints for how a client and a server exchange data – most commonly over HTTP. REST is a set of design rules, not a protocol like SOAP (Simple Object Access Protocol), so there's no spec to install or library to import.

You either design your API to follow the rules or you don't.

Computer scientist Roy Fielding first defined REST in his 2000 doctoral dissertation, as a way to keep client-server communication over the web predictable at scale.

The core idea still holds up two decades later: a client sends a request, and a server sends back a representation of a resource's current state, usually as JSON (JavaScript Object Notation), though REST doesn't require any particular format.

That resource-based thinking is what separates REST from a pile of ad-hoc HTTP endpoints. Instead of designing an endpoint around an action, like /getUser or /deleteOrder, a REST API treats "user" or "order" as a resource with its own uniform resource identifier (URI), and lets standard HTTP methods say what you're doing to it.

What does REST stand for?

REST stands for representational state transfer, with each word mapping to part of the exchange:

• Representational – the format the server sends back, describing a resource without being the resource itself.
• State – the resource's current data at the moment of the request.
• Transfer – that state moving from server to client over HTTP.

Put together, a REST API transfers a representation of a resource's state, on request, over standard web protocols.

The six REST architectural constraints

An API earns the RESTful label by satisfying six constraints. Five are required, and one is optional:

Constraint	What it means
Client-server architecture	The client and server are separate. Either side can change or scale independently as long as the interface between them stays the same.
Statelessness	Each request carries everything the server needs to process it. The server doesn't store client session state between requests.
Cacheability	Responses say whether they can be cached, which reduces server load and speeds up repeat requests for the same data.
Uniform interface	Every resource is identified through a URI in a standard, predictable way, and self-descriptive messages tell the client how to process what it gets back.
Layered system	A client can't tell whether it's connected directly to the server or to an intermediary, such as a load balancer or an API gateway. Neither the client nor these in-between layers need to know about each other.
Code on demand (optional)	The only optional constraint. A server can occasionally send executable code that the client runs to extend its own functionality.

Most APIs called "RESTful" in practice don't rigorously implement every constraint.

Hypertext As The Engine Of Application State (HATEOAS), part of the uniform-interface constraint, is the idea that a response includes links to every other action currently available. APIs that use "RESTful" loosely omit it constantly, since it usually adds design overhead for limited practical benefit.

In everyday use, "REST API" has become shorthand for a resource-oriented HTTP API that uses standard methods and status codes.

REST API vs. API, SOAP API and RESTful API

• REST API vs. API – Every REST API is an API, but not every API is a REST API. "API" is the general term for any interface that lets one piece of software talk to another. "REST API" narrows that down to an API that follows REST's architectural style over standard HTTP.
• REST API vs. SOAP API – A SOAP API is also an API, just one built on a stricter protocol based on XML (Extensible Markup Language), with its own messaging rules instead of REST's constraints.
• REST API vs. RESTful API – These two terms usually mean the same thing. Technically, a RESTful web API satisfies all of REST's required constraints, including a complete uniform interface. In practice, most APIs marketed as "REST APIs" skip HATEOAS and are still described as RESTful.

How does a REST API work?

The clearest way to understand a REST API is to look at a real one instead of an abstract "/users/123" example.

Here's an actual request to a Browserless REST API endpoint that renders a page and captures it as an image:

curl -X POST \
  "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE" \
  -H "Cache-Control: no-cache" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/",
  "options": {
    "fullPage": true,
    "type": "png"
  }
}' \
  --output "screenshot.png"

Three things in this request are worth taking note of when it comes to REST API best practices:

1. The endpoint (/screenshot).
2. The HTTP method (POST).
3. The request body, which tells the API what to do and how, in this case, which URL to render and how to format the image.

On the way back, the response includes a status code, response headers, and a response body, which here is the PNG image itself rather than JSON.

REST doesn't require JSON specifically; it requires a representation the client can use, and an image qualifies just as much as a data structure would.

Common HTTP methods in REST APIs

Every REST API request uses an HTTP method that tells the server what to do with a resource:

Method	Action	Idempotent?
GET	Retrieve a resource without changing it	Yes
POST	Create a new resource, or trigger an action like the screenshot above	No
PUT	Replace an existing resource entirely	Yes
PATCH	Update part of an existing resource	Not guaranteed
DELETE	Remove a resource	Yes

Idempotent means that sending the exact same request multiple times leaves the server in the same state as sending it once (the response body or status code may differ), which is important during retries: if a network call to a PUT or DELETE request fails and you resend it, you get the same outcome.

Resending an identical POST can create a second resource, which is why APIs that need safe retries on writes often add an idempotency key rather than relying on the method alone.

What's the best REST API for browser automation and web scraping?

A REST API turns a browser task into a single stateless HTTP request, the exact request-response pattern covered above, applied to rendering a page instead of fetching a database record.

Browserless builds its REST APIs around this idea, with each endpoint mapping to one browser task:

• /screenshot and /pdf – capture a rendered page as visual or print output.
• /content – return fully rendered HTML.
• /scrape – structured data extraction using CSS (Cascading Style Sheets) selectors.
• /unblock – reach sites with bot detection or CAPTCHA (advanced fingerprinting and interactive CAPTCHAs are better handled by BrowserQL).
• /function – run your own Puppeteer code in a real browser on Browserless's infrastructure, for workflows that don't fit a single-purpose endpoint.
• /smart-scrape – scrape with automatic fallbacks between a lightweight fetch and a full browser render.
• /search – run a web search and scrape the result pages.
• /map – discover URLs across a site or sitemap.
• /crawl – walk an entire site and scrape every page.

Every one of these is a textbook illustration of statelessness in practice: a request comes in, the endpoint runs its task – a lightweight HTTP fetch, or a full browser only when the page needs it – returns a result, and keeps nothing for the next call.

A plain REST API also hits its limit at this point. A single request can chain multiple actions, but statelessness means none of the browser's state persists between calls, so one request can't act on what a previous request left behind.

For workflows that genuinely need that continuity, Browserless offers session persistence, built on browsers-as-a-service (BaaS) session management or BrowserQL's reconnect mutation rather than a single-action endpoint like /screenshot, plus BrowserQL for stealth-heavy, multi-step automation that a single stateless call was never designed to handle.

Conclusion

A REST API is ultimately an API that agrees to a specific set of rules, mainly statelessness and a uniform, resource-based interface, in exchange for being predictable and easy to scale.

REST APIs show their limitations when a stateless request has to render an entire browser page instead of returning a row from a database.

If you want to overcome those limitations in your workflow, sign up for a free Browserless account and send a real request to a live REST endpoint. You'll have a screenshot or a PDF back within seconds, plus a much clearer sense of what a REST API is actually doing behind the scenes.

REST API FAQs

What is a REST API used for?

REST APIs are used any time two systems need to exchange data or trigger an action over HTTP in a predictable, resource-oriented way. That definition covers a weather app pulling a forecast and a payment processor confirming a charge, and it stretches all the way to a browser automation platform rendering a screenshot on request.

Is a REST API the same as HTTP?

No, HTTP is the underlying protocol that carries the requests and responses; REST is an architectural style that governs how those requests and responses should be structured and used. A REST API relies on HTTP, but plenty of HTTP requests aren't part of any REST API at all.

Why is REST API so popular compared to SOAP?

REST APIs are often lighter-weight than SOAP, which uses XML messaging and a stricter extensibility model (e.g., optional WS-* extensions) that can add overhead many web APIs don't need.

REST leaves the data format and much of the implementation detail up to the developer, which makes it faster to build, easier to scale, and generally a better fit for web and mobile applications than SOAP's stricter, more rigid structure.