What is a REST API? | Glossary

A REST API is a web API organised around "resources" such as customers, orders or products, each living at its own URL. You read and change those resources with the standard verbs of HTTP, the same protocol your browser uses to load pages.

The building blocks: URLs, verbs and status codes

REST stands for Representational State Transfer, a set of design constraints described by Roy Fielding in his 2000 doctoral dissertation. In everyday use it boils down to a few conventions:

• Nouns in the URL. /orders is the collection, /orders/1042 is one order.
• Verbs from HTTP. GET reads, POST creates, PUT or PATCH updates, DELETE removes.
• Status codes for outcomes. 200 means fine, 201 means created, 404 means no such resource, 401 means you are not authenticated, 429 means slow down.
• Stateless requests. Each call carries its own credentials; the server does not remember the previous call.

Responses are usually JSON. Because GET requests are meant to be safe and repeatable, they can be cached by browsers and CDNs, which is one practical advantage of following the style properly.

Example: reading an order from Shopify

Shopify's Admin REST API lets an app request a single order with a GET to a URL ending in /orders/{id}.json, sending an access token in a header. Shopify answers with the order's line items, totals and customer. To add a note, the app sends a PUT to the same URL with the changed field. Shopify now recommends its GraphQL API for new apps, a good reminder that providers shift styles over time.

When REST is the right fit for your site

Most services a small business connects to (Stripe, Mailchimp, Twilio, many booking tools) offer REST endpoints, so any developer or automation tool can work with them using ordinary HTTP. You rarely choose REST yourself; you choose vendors, and their REST documentation tells you what your site can do with them. If you are commissioning a custom app, REST is the safe default unless the front end needs to stitch many related records together, where GraphQL can save round trips.

Where REST designs go wrong

• Using GET to change data. Link prefetchers and crawlers follow GET URLs, so a "GET /delete-item" can wipe records.
• Returning 200 for errors. Clients and monitoring tools then think failures succeeded.
• Overfetching in loops. Requesting each of 50 products one by one instead of using a list endpoint with filters.
• Skipping versioning. Changing a field name without a /v2 path breaks every existing integration.

Related terms

• API: the broader idea REST is one style of.
• GraphQL: a single-endpoint alternative.
• HTTPS: the secure transport REST calls travel over.
• Webhook: push notifications that often pair with REST lookups.