Skip to main content

REST API

Representational State Transfer API

Updated 2 min read

Share this page

Send the link, quote the definition with a link back, or show it as a card on your own site.

https://softwaredictionary.org/terms/rest-api

In short

A REST API is a web API that exposes data as resources identified by URLs and lets clients read or change them using standard HTTP methods.

What is a REST API?

A REST API organizes an application's data into resources, such as users, orders, or products, and gives each one its own URL. Clients work with those resources by sending HTTP requests, and the server usually responds with data in JSON format. REST stands for Representational State Transfer, an architectural style described by Roy Fielding in 2000.

The HTTP method tells the server what to do: GET reads a resource, POST creates one, PUT or PATCH updates it, and DELETE removes it. Status codes in the response, such as 200 OK, 201 Created, or 404 Not Found, report the result. Each request is stateless, meaning it carries everything the server needs, such as an authentication token, so the server does not have to remember earlier requests.

Think of a REST API like a library catalog: every book has a fixed shelf address, and a small set of standard actions (look up, add, update, remove) works the same way for every book. This predictability is why REST is the most common style for public web APIs and for communication between a frontend and its backend.

REST is often compared with GraphQL. A REST API has many endpoints that each return a fixed shape of data, while a GraphQL API usually has a single endpoint where the client describes exactly which fields it wants. REST is simpler to cache and reason about, while GraphQL can reduce the number of requests for complex, nested data.

How it works

  1. Each thing has an address

    Every resource the API offers, such as a user or an order, has its own URL.

    /users/42
  2. The method says what to do

    The HTTP method says whether to read it, create one, change it or delete it.

    GET POST PUT DELETE
  3. The server answers

    It sends back the resource, usually as JSON, with a status code that says how it went.

    200 OK · 404 Not Found
  4. Nothing is remembered

    Each request carries all it needs, such as the token. The server keeps no session between requests.

    Authorization: Bearer …

Often misunderstood

You might think: Any API that returns JSON over HTTP is a REST API.

In fact: REST is a set of design rules: resources with their own URLs, the standard HTTP methods and status codes, and requests that stand on their own. One endpoint that takes every action in its body is HTTP and JSON, but not REST.

At a glance

Four REST requests on the users resource: GET /users returns the list with 200 OK, POST /users creates a user and returns 201 Created, GET /users/42 returns that user as JSON with 200 OK, and DELETE /users/42 removes it and returns 204 No Content.request: method + URLresponse: status + JSONreads the listGET /users200 OK[{ "id": 41 }, { "id": 42 }]creates a userPOST /users201 Created{ "id": 43 }reads user 42GET /users/42200 OK{ "id": 42, "name": "Ada" }deletes user 42DELETE /users/42204 No Content
The URL names the resource and the HTTP method says what to do with it; the status code and JSON in the response report the result.

Key takeaways

  • REST is an architectural style, not a protocol or a formal standard.
  • Resources are identified by URLs, such as /users/42.
  • HTTP methods (GET, POST, PUT, PATCH, DELETE) describe the action.
  • Requests are stateless: each one carries all the information the server needs.
  • Responses usually contain JSON and an HTTP status code.

Example

Calling a REST API with curlbash
# Read a list of users
curl https://api.example.com/users

# Read one user by ID
curl https://api.example.com/users/42

# Create a new user by sending JSON
curl -X POST https://api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Ada"}'

# Delete a user
curl -X DELETE https://api.example.com/users/42

Readers ask

What is the difference between REST and RESTful?

They mean practically the same thing. REST is the architectural style, and an API described as RESTful is one that follows its principles, such as resource URLs, standard HTTP methods, and stateless requests.

What is the difference between a REST API and GraphQL?

A REST API exposes many endpoints that each return a fixed data shape, while GraphQL usually exposes one endpoint where the client asks for exactly the fields it needs. REST is simpler and easier to cache; GraphQL is more flexible for complex, nested data.

What is the difference between PUT and PATCH?

PUT replaces the whole resource with the data you send, while PATCH updates only the fields you include. Many APIs use PATCH for partial updates and PUT for full replacement.

See also

Free · once a week

Software and AI, explained once a week

The week's software and AI news with every term explained, plus a term to learn and a quick quiz. A two-minute read.

You confirm by email first, and one click unsubscribes. Privacy

See this week's issue

About this page

Page history

  1. Added "How it works": resources, methods, answers and stateless requests, and what makes an API RESTful.

Changes that altered what this page says. Typo fixes are not listed.

Spotted a mistake or something missing on this page?Suggest an edit

How pages are made

More

Settings