← Learn
What is REST?
REST stands for Representational State Transfer. It's an architectural style for building web services — a set of rules and conventions that describe how client and server should communicate over the internet.
REST was described by computer scientist Roy Fielding in his 2000 doctoral dissertation. He was looking at how the web itself worked and formalised the principles that made HTTP scalable and reliable. Almost every public API you'll encounter today follows these principles.
Analogy: Think of REST like the rules of ordering at a restaurant. You (the client) give a specific order (request) to the waiter (the API). The kitchen (the server) prepares it. The waiter returns your food (the response). The kitchen doesn't need to remember your previous orders — each request is independent.
The key thing to understand about REST is that it is not a protocol or a standard — it's a style. An API is called "RESTful" when it follows REST conventions: using standard HTTP methods, returning data in a predictable format (usually JSON), and treating everything as a named resource with a URL.
How a REST request works
Every REST interaction follows the same basic flow: your app sends an HTTP request to a URL, the server processes it, and returns a response.
Your AppClient
→ request →
API ServerREST endpoint
← response ←
Your Apphandles data
A REST request has four parts:
Method
The action you want to take — GET, POST, PUT, DELETE. Tells the server what to do with the resource.
URL (endpoint)
The address of the resource you're acting on — e.g. https://api.example.com/users/42.
Headers
Extra metadata sent with the request — your API key, the format you want back, content type.
Body (optional)
Data you're sending — used with POST and PUT to create or update a resource. Usually formatted as JSON.
The server returns a response with a status code (a number like 200 or 404) and usually a body containing the requested data, formatted as JSON.
The HTTP methods
REST uses standard HTTP methods to describe what action you want to perform. Each method has a specific meaning — knowing them lets you read any API at a glance.
GET Read
Retrieve data from the server. Safe to call multiple times — it never changes anything. Example: fetch a user's profile, list all products.
POST Create
Send new data to the server to create a resource. Example: submit a new order, register a new account, upload a file.
PUT Replace
Replace an existing resource entirely. You send the full object. Example: update all fields of a user record at once.
PATCH Update
Partially update a resource — only the fields you include are changed. Example: update just a user's email address.
DELETE Remove
Delete a resource from the server. Example: remove a file, cancel a subscription, delete a post.
Tip: In practice, most REST APIs only use GET and POST heavily. PUT, PATCH, and DELETE are common in management APIs but rare in read-only data APIs.
Status codes
Every REST response includes a three-digit HTTP status code that tells you immediately whether the request succeeded or what went wrong. You'll encounter these constantly.
200 OK
Request succeeded. The response body contains the data you asked for.
201 Created
A new resource was successfully created (typically after a POST request).
204 No Content
Success, but there's nothing to return — common after a DELETE.
400 Bad Request
Your request was malformed — missing a required field, wrong data type, or invalid format.
401 Unauthorized
You didn't provide authentication, or your API key / token is invalid.
403 Forbidden
You're authenticated but don't have permission to access this resource.
404 Not Found
The resource doesn't exist at that URL — wrong ID, typo in the path, or deleted.
429 Too Many Requests
You've hit the API's rate limit. Slow down and retry after a delay.
500 Server Error
Something went wrong on the server — not your fault. Wait and retry.
A simple rule: 2xx = success, 4xx = your error, 5xx = their error.
Reading a REST endpoint
Every REST endpoint is a URL that identifies a specific resource. Once you know how to read them, all REST APIs start to look familiar.
https://api.example.com/users/{id}/posts?limit=10&page=2
Protocol (https://)
Always use HTTPS for API calls — it encrypts your request and response so credentials and data can't be intercepted.
Host (api.example.com)
The server where the API lives. Often has a subdomain like api. or v1. to distinguish it from the main website.
Path (/users/{id}/posts)
Identifies the resource. Parts in curly braces like {id} are placeholders — replace them with a real value, e.g. /users/42/posts.
Query params (?limit=10)
Optional filters or options. Start with ? and are separated by &. Common uses: pagination, filtering, sorting.
REST APIs are designed to be self-describing through their URLs. A well-designed REST API lets you guess what an endpoint does just by reading its path: /orders/123 is order number 123, /orders/123/items are the items in that order.
REST vs SOAP vs GraphQL
REST is the dominant API style today, but you may encounter two alternatives: SOAP and GraphQL.
REST
Lightweight, uses standard HTTP methods and JSON. Predictable URLs, easy to cache, works everywhere. The default choice for new APIs.
SOAP
Older, enterprise-focused. Uses XML instead of JSON, with a rigid envelope format. More verbose and complex, but common in banking and government systems.
GraphQL
A query language for APIs. Instead of fixed endpoints, you send a query describing exactly the data you want. Flexible but more complex to learn. Used by GitHub, Shopify, and others.
For the vast majority of APIs you'll work with — weather, payments, social media, maps — you'll be using REST. All APIs in the Find an API catalog that have sample requests are REST APIs.