Despite the rise of GraphQL, gRPC, and other API styles, RESTful APIs remain the backbone of most web services because they're simple, predictable, and built on HTTP—the universal language of the internet.
At Stainless, we work with hundreds of API companies, and the vast majority still choose REST for their public APIs. This guide breaks down what makes an API truly RESTful, why these principles matter for your engineering team, and how REST APIs are uniquely positioned for the AI era through tools like Model Context Protocol servers.
RESTful API stands for Representational State Transfer Application Programming Interface. It's an architectural style that uses standard HTTP methods to create a predictable, stateless, and scalable way for different software systems to communicate over the internet.
At Stainless, we obsess over API design because a well-structured API is the foundation for a great developer experience, which is why we help companies generate high-quality SDKs and AI-ready interfaces directly from their API specifications, since your API isn't finished until the SDK ships.
Rest acronym decoded
RESTful API stands for Representational State Transfer Application Programming Interface. It's less of a strict protocol and more of an architectural style—a set of design principles for building networked applications. When an API adheres to these principles, we call it RESTful.
The core idea is to treat everything as a resource. These resources are manipulated using a common set of operations, like GET or POST, which makes the API predictable. This predictability is what allows tools like the Stainless SDK generator to automatically generate client SDKs directly from a machine-readable definition like an OpenAPI spec.
Representational concept
When you interact with a REST API, you never get direct access to the database record or the raw object on the server. Instead, you receive a representation of that resource at a specific point in time. This representation is typically in a standardized format like JSON or, less commonly today, XML.
For example, asking the API for user 123 doesn't give you the user object itself. It gives you a JSON document that represents the user's current data. Your application then works with this snapshot.
State concept
The "State" in REST refers to the state of a resource on the server, like the current data for a specific user or product. The "Transfer" part simply means the server transfers a representation of that resource's state to the client.
When you send a PUT request with modified JSON to update a user, you are transferring a new representation of the desired state back to the server. The server then updates its internal resource state to match.
Transfer concept
"Transfer" is the action of moving these state representations between the client and server. This process uses the standard HTTP protocol, the same one your browser uses to fetch web pages.
This reliance on a universal, well-understood protocol is a key reason for REST's simplicity and widespread adoption. It doesn't require specialized tooling to get started; any HTTP client can speak REST.
Rest constraints that define a truly RESTful API
To be considered truly RESTful, an API should follow six guiding constraints. Think of them less as rigid rules and more as engineering best practices that lead to a more scalable, maintainable, and decoupled system.
Uniform interface
This is the most critical principle. It dictates that the way you interact with any resource in the API should be consistent and predictable. It's achieved through a few key sub-constraints:
Resource Identification: Every resource is uniquely identified by a URI (Uniform Resource Identifier), like
/users/123. This is the resource's address.Resource Manipulation: You use standard HTTP methods (
GET,POST,PUT,DELETE) to act on these resources. The verb tells the server what action to perform on the noun (the URI).Self-descriptive Messages: Each request and response contains enough information for the other party to understand it. For example, a response includes a
Content-Typeheader likeapplication/jsonso the client knows how to parse the body.
Client-server split
The client (the application making the request) and the server (the application providing the API) are completely separate. The client only needs to know the resource's URI; it doesn't know or care how the server is implemented, what database it uses, or what language it's written in.
This separation of concerns is powerful. It allows the frontend and backend teams to evolve their systems independently, as long as the API contract—the interface—remains unchanged.
Stateless interaction
This is a cornerstone of REST's scalability. Every request from a client to the server must contain all the information needed for the server to understand and process it. The server does not store any client context or session state between requests.
No server-side sessions: The server doesn't remember if you've made a request before. Authentication information, for example, must be sent with every single request.
Scalability: Because any server instance can handle any request, it's easy to scale horizontally by simply adding more servers behind a load balancer.
Reliability: Statelessness simplifies error recovery. If a request fails, a client SDK can safely retry it without worrying about creating duplicate state on the server (especially when paired with idempotency keys).
Cacheable response
To improve performance and reduce server load, responses should explicitly declare whether they are cacheable. If a response for GET /users/123 is marked as cacheable, the client can store it and reuse it for a period of time instead of making the same request again.
This is typically controlled via standard HTTP headers like Cache-Control and ETag.
Layered system
A client cannot ordinarily tell whether it is connected directly to the end server or to an intermediary along the way. This allows you to introduce layers like load balancers, proxies, or security gateways into the architecture without affecting the client.
This principle is also what enables modern AI interfaces. An MCP server can act as an intelligent layer between an LLM agent and your core API, translating natural language into structured API calls without the end client's knowledge.
Code on demand (optional)
This is the only optional constraint of REST. It allows a server to temporarily extend or customize the functionality of a client by transferring executable logic, like a script. In practice, this is very rarely used in modern web APIs.
Engineering impact of REST on modern teams
Adhering to REST principles isn't just an academic exercise. It has a direct, positive impact on how development teams build and maintain software.
Faster onboarding
Because RESTful APIs are predictable, a new developer can quickly understand how to use one. They know that to fetch a list of products, they'll likely make a GET request to /products. This consistency, especially when paired with a well-documented OpenAPI spec and a strongly-typed SDK (which can integrate SDK snippets with your API docs), dramatically reduces the learning curve.
Simpler scaling
The stateless nature of REST is a massive win for scalability. Since no session state is stored on the server, you can easily add more server instances to handle increased traffic. Any server can handle any request, which is a perfect fit for modern cloud, serverless, and container-based deployments.
Lower coupling
The strict separation between client and server means your frontend and backend teams can work in parallel with minimal friction. As long as the API contract is respected, backend changes won't break the client, and UI updates won't require backend modifications. This allows for faster, more independent development cycles.
Why REST remains the default web API style
While other API styles have emerged, REST has remained the dominant choice for web APIs for several practical reasons.
Simplicity advantage over SOAP
Before REST became popular, SOAP was a common standard. However, SOAP is a rigid protocol that often requires complex XML and specialized tooling. REST's use of simple JSON over standard HTTP made it far more accessible, lightweight, and human-readable.
Complement to GraphQL and gRPC
Newer styles like GraphQL and gRPC are powerful tools for specific problems.
API Style | Best For |
|---|---|
REST | Standard resource-based CRUD operations, public APIs |
GraphQL | Complex data queries, mobile apps, flexible clients |
gRPC | High-performance, low-latency internal microservices |
GraphQL is excellent for complex data queries where clients need to specify exactly which fields they need. gRPC is great for high-performance, low-latency internal communication between microservices. However, for standard, resource-oriented web APIs, REST's simplicity and universal HTTP compatibility often make it the more pragmatic choice.
Ecosystem momentum
The entire web is built around HTTP, and so is REST. This has led to a massive ecosystem of tools, libraries, frameworks, and developer knowledge. This momentum means it's easier to find documentation, hire developers, and leverage existing infrastructure when building a RESTful API.
Rest meets the AI era through MCP servers
The Model Context Protocol (MCP) is an open standard that allows Large Language Models (LLMs) to interact with APIs, and RESTful APIs are uniquely suited for this transformation from API to MCP.
Mapping endpoints to tools
A well-designed REST API can be programmatically converted into a set of "tools" that an LLM can use by creating an MCP server from an OpenAPI spec. Each endpoint, like POST /products, becomes a distinct action, like a create_product tool with a defined input schema. This direct mapping allows an LLM to understand and invoke your API's capabilities.
Benefit of statelessness for LLM agents
LLM agents work best with stateless, self-contained operations. A stateless API call is a perfect fit, as the agent doesn't need to maintain any server-side context. This makes interactions more reliable and resilient, especially when retries are needed to overcome transient errors or model hallucinations.
Quick path from OpenAPI to AI-ready server
Because REST APIs are often described by a machine-readable OpenAPI specification (and you can create OpenAPI specs using various tools), you can automate the creation of an AI-ready interface. The flow is straightforward: import your OpenAPI spec, generate your core SDKs, and simultaneously generate an MCP server that exposes your API to AI agents.
Frequently asked questions about RESTful APIs
What are the common HTTP methods?
The most common methods map to CRUD (Create, Read, Update, Delete) operations. These include GET to read a resource, POST to create a new resource, PUT or PATCH to update an existing resource, and DELETE to remove a resource.
Is every HTTP API automatically RESTful?
No. An API can use HTTP without following the REST constraints. An API that uses POST for all operations (an RPC-style API) or relies on server-side cookies for session management is not RESTful, even though it uses HTTP.
When should I avoid REST?
For applications requiring real-time, bi-directional communication (like a live chat app or a collaborative editor), WebSockets might be a better fit. For APIs with highly complex, interconnected data that clients need to query flexibly (like a social network feed), GraphQL is often a superior choice.
How can I check if my API is RESTful enough?
A practical way is to use the Richardson Maturity Model. It has four levels, from Level 0 (using HTTP as a basic transport system) to Level 3 (fully embracing hypermedia controls), which helps you gauge how closely your API aligns with core REST principles.
Ready to provide a first-class developer experience for your REST API? Get started for free and generate high-quality, idiomatic SDKs from your OpenAPI spec in minutes.