What is a REST API? The 2026 Definitive Guide

REST in one sentence

REST (Representational State Transfer) is an architectural style for APIs that treats everything as a resource, identifies resources with URLs, and uses HTTP methods to act on them.

It was introduced in Roy Fielding's 2000 PhD dissertation and became the dominant API style for the 2010s and 2020s. In 2026, "REST API" is the default assumption when someone says "API" without qualifying.

The core ideas

REST has six formal constraints. Most people only need three:

1. Resources identified by URLs — every thing in your system has a URL: /users/123, /products/abc, /orders/456/line-items/1.
2. Uniform interface — the HTTP methods (GET, POST, PUT, PATCH, DELETE) mean the same thing regardless of what resource you're acting on.
3. Stateless — each request contains everything the server needs to process it. The server doesn't remember previous requests. Authentication is sent every time.

The other three (client-server, cacheable, layered) are architectural principles that modern web frameworks handle for you automatically.

What REST looks like in practice

A "truly RESTful" API around a user record looks like:

GET    /users         → list users
GET    /users/123     → read one user
POST   /users         → create a user
PUT    /users/123     → replace a user
PATCH  /users/123     → update a user
DELETE /users/123     → delete a user

URLs are nouns. Methods are verbs. No /getUsers, no /deleteUser?id=123 — those encode the verb in the URL and break REST's uniformity.

curl -X GET 'https://demo.totalshiftleft.ai/api/v1/users'

REST is not a standard

Here's the dirty secret: "REST" in the real world is a spectrum. Roy Fielding's original REST (sometimes called "HATEOAS REST") includes hypermedia — each response tells the client what actions are possible next. Almost no API in production follows HATEOAS strictly.

What most 2026 APIs call "REST" is more accurately called resource-oriented HTTP JSON APIs:

• Resources identified by URLs ✓
• HTTP methods as verbs ✓
• JSON request/response bodies ✓
• No hypermedia ✗
• Some endpoints that don't map cleanly to CRUD (POST /orders/123/refund) ✓ accepted

This is fine. Dogmatic REST has proven less useful than pragmatic REST. What matters is consistency within your API.

Why REST won

Three reasons REST dominated SOAP and other earlier API styles:

1. It rides on HTTP. Every browser, CDN, load balancer, and proxy already speaks HTTP. No new infrastructure needed.
2. It's debuggable with a browser. A REST GET endpoint is literally a URL you can paste into your address bar.
3. JSON is lightweight. Compared to SOAP's XML envelopes, REST/JSON is 5-10x smaller over the wire and trivial to parse in any language.

Where REST struggles

REST has real weaknesses, which is why GraphQL and gRPC emerged:

• Over-fetching — GET /users/123 returns the full user object, even if you only need their name.
• Under-fetching — listing a user's posts might require /users/123 then /users/123/posts, two round-trips.
• Versioning is painful — changing response shapes breaks clients; most teams end up with /v1/ and /v2/ forever.
• No streaming — REST is request/response only. For live data, you reach for WebSockets or SSE.

We compare REST honestly against GraphQL and SOAP in the big comparison lesson.

What testers need to know about REST

Because REST maps cleanly to HTTP methods + resource URLs, it's easy to test systematically:

• Every resource type × every method = one test case.
• Status codes and error envelopes should be consistent across the API (if GET /users returns { error, message } on failure, GET /products should use the same shape).
• Pagination and filtering should work the same way on every list endpoint.

The consistency is what makes REST tests generatable from an OpenAPI spec. If your API uses REST conventions, a spec-driven tool like ShiftLeft can write 80% of your test suite without a human writing a single expect().

What's next

You've got the concept. Next: REST CRUD explained end-to-end — the most common pattern in REST, walked through step by step with runnable code.