What Is a REST API? How It Works, With Real Examples
REST API is one of the most searched terms in web development and one of the most poorly explained. Here is exactly what it is, why it was designed the way it was, and what every part of it means, with real examples throughout.
Most guides on REST APIs either make the topic too abstract or dive straight into code before building any mental model. This guide does neither. It starts with what REST actually means, walks through every component with real examples, and finishes with a practical checklist you can use immediately when working with any REST API.
What REST Stands For
REST stands for Representational State Transfer. It was defined in 2000 by Roy Fielding in his doctoral dissertation. Fielding was one of the primary authors of the HTTP specification, and REST was his description of the architectural style that made the web work as well as it did.
The name sounds technical. The concept is not. REST is simply a set of conventions for building APIs that use the web's existing infrastructure, namely HTTP, rather than inventing something new on top of it. By following REST conventions, any API becomes predictable: a developer who knows one REST API can figure out another one quickly, regardless of which company built it or what programming language runs the server.
This predictability is REST's greatest value. Before REST, every API had its own format, its own conventions, and its own rules. REST standardised the approach so that the knowledge transfers.
REST did not invent anything new. It described the principles already present in HTTP and said: if you follow these principles when building an API, any client can use it predictably.
The Six Constraints of REST
REST is formally defined by six architectural constraints. You do not need to memorise all six, but understanding them explains why REST APIs behave the way they do. The two that matter most in day-to-day work are highlighted:
Stateless means each request is self-contained. Your API cannot rely on the server remembering a previous request. This is why authentication tokens are sent with every request rather than once at login. Uniform Interface is why REST APIs are so learnable: the same methods, the same URL patterns, and the same status codes apply everywhere.
How a REST API Request Works
Every REST API interaction follows the same flow:
Client → HTTP Request → Server → HTTP Response → Client
A request and its response each have distinct components. Understanding both is essential for debugging API issues:
The Four HTTP Methods — With Real Examples
The HTTP method tells the server what operation to perform. Four methods cover every possible data operation. Each one has a specific meaning and a specific expected behaviour:
HTTP Status Codes — The Language of API Responses
Status codes tell you exactly what happened with a request. Every REST API uses the same codes, which is one of the benefits of the uniform interface constraint. Always check the status code before processing the response body:
| Code | Meaning | When You See It | Action Required |
|---|---|---|---|
| 200 | OK | Request succeeded, data returned | Validate structure before using |
| 201 | Created | POST succeeded, new resource created | Use the returned ID for follow-up requests |
| 204 | No Content | DELETE succeeded, nothing to return | No body processing needed |
| 400 | Bad Request | Request is malformed or missing fields | Log the error body, fix the request format |
| 401 | Unauthorised | Missing or invalid authentication token | Trigger token refresh or re-authentication |
| 403 | Forbidden | Valid auth, but insufficient permissions | Show permission error to user, do not retry |
| 404 | Not Found | Resource does not exist or was deleted | Handle gracefully, not a crash condition |
| 429 | Too Many Requests | Rate limit exceeded | Implement exponential backoff, check Retry-After header |
| 500 | Internal Server Error | Bug on the server side | Log, retry with backoff, alert if persistent |
| 503 | Service Unavailable | API is down or overloaded | Queue for retry, do not surface raw error to users |
Always check the status code first, then validate the response structure. An API may return 200 with an unexpected shape if an internal transformation fails. Validate that required fields are present and have the expected types before processing. Use the JSON Formatter to inspect real responses before writing integration code.
REST API URLs — How Resources Are Structured
REST APIs organise URLs around resources, the nouns. Operations are expressed through the HTTP method, the verb. This separation is what makes REST URLs intuitive and consistent across any API.
The URL describes what you are acting on. The method describes what you are doing to it. You never need to see a URL like /getUser or /deletePost in a REST API:
Notice that the same URL /users/42 is used for GET, PUT, and DELETE. The URL stays constant. The method changes the operation. This is the uniformity that makes REST predictable.
Authentication — How APIs Know Who You Are
Because REST is stateless, every request must carry its own authentication. The server cannot remember that you authenticated in a previous request. There are three common approaches, each suited to different use cases:
Never hardcode an API key in your source code. Even in a private repository, keys committed to git history remain there forever. Always store API keys in environment variables or a secrets manager. If a key is ever accidentally committed, treat it as compromised and rotate it immediately.
REST vs GraphQL vs gRPC vs SOAP
REST is not the only API architecture. Understanding how it compares to the alternatives helps you choose the right approach for your use case:
| Feature | REST | GraphQL | gRPC | SOAP |
|---|---|---|---|---|
| Data format | JSON | JSON | Protocol Buffers | XML |
| Flexibility | Fixed responses | Client controls fields | Fixed contract | Fixed contract |
| Performance | Good | Good | Excellent | Slow (XML parsing) |
| Human-readable | Yes | Yes | No (binary) | Verbose XML |
| Learning curve | Low | Medium | High | High |
| Best for | Web and mobile APIs | Complex data needs | Internal microservices | Legacy enterprise |
For most web and mobile applications, REST is the right starting point. It is simple, widely supported, well-documented, and understood by every developer on any hiring market. GraphQL adds complexity that is only worth it when you have genuinely complex data fetching needs. gRPC is excellent for internal service-to-service communication where performance is critical. SOAP appears when a legacy enterprise system requires it.
A Checklist for Working With Any REST API
Before writing integration code with a new API, work through this checklist. Each item prevents a class of bugs that consistently appears in real-world integrations:
-
✓Read the full documentation before writing a single line of code, especially the rate limits, auth requirements, and error response formats.
-
✓Get a real response sample and format it with the JSON Formatter to understand the actual structure, not just the documentation version.
-
✓Note all nullable fields before assuming they are always present. Missing field access is one of the most common silent bugs in API integrations.
-
✓Write explicit handlers for 401, 403, 404, 429, and 5xx responses. Happy-path-only code fails silently in production.
-
✓Implement pagination for any endpoint that returns a list. The first page is never all the data.
-
✓Store API keys in environment variables. Never in source code. Never in a file committed to version control.
-
✓Add caching for data that does not change frequently. Every redundant API call costs latency and burns rate limit quota.
-
✓Compare responses across environments before debugging production issues. Environment divergence is one of the most common sources of production-only bugs.
Frequently Asked Questions
An API (Application Programming Interface) is any defined way for two systems to communicate. A REST API is a specific type of API that follows the REST architectural constraints: stateless, uniform interface, resource-based URLs, and standard HTTP methods. All REST APIs are APIs, but not all APIs are REST APIs. SOAP APIs, GraphQL APIs, and gRPC APIs are all APIs that are not REST.
Stateless means the server does not store any session information between requests. Each request must carry all the context the server needs to process it, including the authentication token, user ID, and any relevant parameters. In practice this means: you cannot log in once and have the server remember you. Every request includes the token. This is why you stay logged into apps even when the server restarts: your token is stored client-side and sent with every request.
PUT replaces the entire resource with the data you send. If you send a PUT request with only the plan field, the server replaces the whole user object with just that field. PATCH applies a partial update: only the fields you send are changed, everything else remains. In practice many APIs accept partial data with PUT anyway, but the strict REST interpretation is that PUT is a full replacement and PATCH is a partial update.
Use REST when: you are building a standard CRUD API, your data relationships are relatively flat, your team is new to APIs, or you need maximum ecosystem compatibility. Use GraphQL when: different clients need different subsets of the same data, you have deeply nested or complex data relationships, you are experiencing significant over-fetching or under-fetching with REST, or you want a single endpoint with a flexible query language. GraphQL adds complexity: schema definition, resolver implementation, and client-side query management. That complexity is only worthwhile when it solves a real problem.
When you receive a 429 Too Many Requests response, implement exponential backoff: wait 1 second, retry; if still 429, wait 2 seconds; then 4 seconds; then 8 seconds. Check the Retry-After header if the API provides one, as it specifies exactly how long to wait. For sustained high-volume operations, implement a client-side request queue that tracks your request rate and stays under the limit proactively rather than reacting to 429 errors after they occur.
Tools for every stage of API work
Format and validate JSON responses, compare API outputs across environments, and convert between data formats. All free, all in your browser, no login required.
REST Is Simple. The Details Make It Reliable.
REST API architecture is straightforward once the mental model is in place: resources identified by URLs, operations expressed through HTTP methods, stateless requests, and uniform conventions across every implementation. That simplicity is the reason REST dominates web development. It uses infrastructure that already exists, follows conventions that are universally understood, and requires no special tooling beyond a standard HTTP client.
What makes the difference between an API integration that works and one that fails silently is the details: reading the full documentation, validating real responses, handling every error code explicitly, implementing pagination and rate limiting, and keeping authentication out of source code. The checklist in this guide covers the full list. Work through it for every new API and you will eliminate the majority of integration failures before they reach production.