In the world of web development, we often hear terms like “REST API” thrown around casually. Many developers claim to build RESTful services, but upon closer inspection, most of these APIs fall short of truly following REST principles. This disconnect between what we call REST and what REST actually is creates confusion and missed opportunities for building truly scalable and flexible web services.<\/p>\n
In this comprehensive guide, we’ll explore what makes a true RESTful API, why most implementations miss the mark, and how you can improve your API design to better align with REST principles.<\/p>\n
REST (Representational State Transfer) is an architectural style for distributed hypermedia systems, introduced by Roy Fielding in his 2000 doctoral dissertation. Fielding, one of the principal authors of the HTTP specification, developed REST as a set of constraints designed to create efficient, reliable, and scalable systems.<\/p>\n
The key insight behind REST is that it’s not a protocol, a standard, or a specific technology. Instead, it’s an architectural style defined by a set of constraints that, when followed, create a specific type of application with particular characteristics.<\/p>\n
Unfortunately, many developers have reduced REST to simply “an API that uses HTTP methods and returns JSON.” This oversimplification misses the core principles that make REST powerful.<\/p>\n
Before diving deeper into what REST is, let’s clear up some common misconceptions:<\/p>\n
While REST commonly uses HTTP as its application protocol, REST is not tied to HTTP. REST is an architectural style that can theoretically be implemented over any application protocol that supports its constraints.<\/p>\n
REST doesn’t specify any particular format for data exchange. While JSON is popular for REST APIs today, REST works with any data format (XML, HTML, plain text, etc.) as long as the media type is properly specified.<\/p>\n
Many developers think that mapping HTTP methods (GET, POST, PUT, DELETE) to CRUD operations (Create, Read, Update, Delete) makes an API RESTful. While this is a good practice, it’s only a small part of REST architecture.<\/p>\n
Proper REST APIs should be evolvable without versioning. Through proper use of media types, hypermedia controls, and other techniques, a true REST API can evolve without breaking existing clients.<\/p>\n
According to Fielding, a truly RESTful system must satisfy six architectural constraints:<\/p>\n
The client and server should be separate from each other and allowed to evolve independently. The server stores and manages the resources while the client requests and displays those resources.<\/p>\n
This separation of concerns improves portability across multiple platforms and improves scalability by simplifying server components.<\/p>\n
Each request from a client to the server must contain all the information needed to understand and process the request. The server cannot use any stored context from previous requests.<\/p>\n
This means session state is kept entirely on the client. This constraint improves visibility, reliability, and scalability.<\/p>\n
Example of a stateful (non-RESTful) interaction:<\/p>\n
\/\/ First request\nPOST \/login HTTP\/1.1\n{\n \"username\": \"user123\",\n \"password\": \"pass456\"\n}\n\n\/\/ Server sets session cookie\n\n\/\/ Second request\nGET \/api\/user\/profile HTTP\/1.1\nCookie: sessionId=abc123\n\n\/\/ Server uses session state to determine user<\/code><\/pre>\nExample of a stateless (RESTful) interaction:<\/p>\n
\/\/ Each request is self-contained\nGET \/api\/user\/profile HTTP\/1.1\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...<\/code><\/pre>\n3. Cacheability<\/h3>\n
Responses must define themselves as cacheable or non-cacheable to prevent clients from reusing stale or inappropriate data in response to further requests.<\/p>\n
Well-managed caching partially or completely eliminates some client-server interactions, improving scalability and performance.<\/p>\n
Example of proper cache headers:<\/p>\n
HTTP\/1.1 200 OK\nCache-Control: max-age=3600\nETag: \"33a64df551425fcc55e4d42a148795d9f25f89d4\"\nContent-Type: application\/json\n\n{\n \"data\": \"This response can be cached for 1 hour\"\n}<\/code><\/pre>\n4. Uniform Interface<\/h3>\n
The uniform interface constraint is fundamental to the design of any RESTful system. It simplifies and decouples the architecture, enabling each part to evolve independently. The uniform interface includes four sub-constraints:<\/p>\n
\n- Resource identification in requests<\/strong>: Individual resources are identified in requests, for example using URIs in web-based REST systems.<\/li>\n
- Resource manipulation through representations<\/strong>: When a client holds a representation of a resource, it has enough information to modify or delete the resource.<\/li>\n
- Self-descriptive messages<\/strong>: Each message includes enough information to describe how to process it.<\/li>\n
- Hypermedia as the engine of application state (HATEOAS)<\/strong>: Clients make state transitions only through actions that are dynamically identified within hypermedia by the server.<\/li>\n<\/ul>\n
This constraint is the most often violated in so-called “REST” APIs.<\/p>\n
5. Layered System<\/h3>\n
A client cannot ordinarily tell whether it is connected directly to the end server or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load balancing and providing shared caches.<\/p>\n
They may also enforce security policies.<\/p>\n
6. Code on Demand (Optional)<\/h3>\n
Servers can temporarily extend or customize client functionality by transferring executable code. Examples include JavaScript, Java applets, and Flash.<\/p>\n
This is the only optional constraint of REST architecture.<\/p>\n
The Richardson Maturity Model<\/h2>\n
Leonard Richardson proposed a model to help categorize the “RESTfulness” of a web service, breaking it down into levels:<\/p>\n
Level 0: The Swamp of POX (Plain Old XML)<\/h3>\n
At this level, you’re essentially using HTTP as a transport protocol for remote interactions, but not taking advantage of any web mechanisms. You typically have a single URL and use POST for all operations.<\/p>\n
Example:<\/p>\n
POST \/api HTTP\/1.1\nContent-Type: application\/json\n\n{\n \"method\": \"getUserProfile\",\n \"userId\": 123\n}<\/code><\/pre>\nLevel 1: Resources<\/h3>\n
At this level, you’re using multiple URIs to identify different resources, but still using a single HTTP method (typically POST) for all operations.<\/p>\n
Example:<\/p>\n
POST \/api\/users\/123 HTTP\/1.1\nContent-Type: application\/json\n\n{\n \"action\": \"getProfile\"\n}<\/code><\/pre>\nLevel 2: HTTP Verbs<\/h3>\n
At this level, you’re using HTTP methods as they were intended. GET for retrieving, POST for creating, PUT for updating, DELETE for removing resources. Most APIs that claim to be RESTful are at this level.<\/p>\n
Example:<\/p>\n
GET \/api\/users\/123 HTTP\/1.1\nAccept: application\/json<\/code><\/pre>\nLevel 3: Hypermedia Controls (HATEOAS)<\/h3>\n
At this level, the API returns not just data but also links to related resources and actions that can be performed. This is the level that qualifies as truly RESTful according to Fielding’s definition.<\/p>\n
Example:<\/p>\n
GET \/api\/users\/123 HTTP\/1.1\nAccept: application\/json\n\nHTTP\/1.1 200 OK\nContent-Type: application\/json\n\n{\n \"id\": 123,\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"_links\": {\n \"self\": { \"href\": \"\/api\/users\/123\" },\n \"profile\": { \"href\": \"\/api\/users\/123\/profile\" },\n \"orders\": { \"href\": \"\/api\/users\/123\/orders\" },\n \"update\": { \n \"href\": \"\/api\/users\/123\",\n \"method\": \"PUT\"\n },\n \"delete\": {\n \"href\": \"\/api\/users\/123\",\n \"method\": \"DELETE\"\n }\n }\n}<\/code><\/pre>\nMost APIs claiming to be RESTful stop at Level 2, missing the crucial hypermedia aspect that makes an API truly RESTful.<\/p>\n
HATEOAS: The Missing Piece<\/h2>\n
HATEOAS (Hypermedia as the Engine of Application State) is perhaps the most distinctive and most frequently overlooked constraint of REST. It’s what separates a truly RESTful API from just an HTTP API.<\/p>\n
With HATEOAS, a client interacts with a network application entirely through hypermedia provided dynamically by application servers. The client needs no prior knowledge about how to interact with the application beyond a generic understanding of hypermedia.<\/p>\n
Why HATEOAS Matters<\/h3>\n
HATEOAS provides several significant benefits:<\/p>\n
\n- API Evolution<\/strong>: You can change your API without breaking clients<\/li>\n
- Self-discovery<\/strong>: Clients can discover capabilities of your API without external documentation<\/li>\n
- Reduced coupling<\/strong>: Clients only need to understand the initial entry point and the hypermedia formats<\/li>\n<\/ul>\n
HATEOAS Example<\/h3>\n
Let’s look at how HATEOAS might work in practice:<\/p>\n
\/\/ Initial request to API entry point\nGET \/api HTTP\/1.1\nAccept: application\/json\n\nHTTP\/1.1 200 OK\nContent-Type: application\/json\n\n{\n \"version\": \"1.0\",\n \"_links\": {\n \"users\": { \"href\": \"\/api\/users\" },\n \"products\": { \"href\": \"\/api\/products\" },\n \"orders\": { \"href\": \"\/api\/orders\" }\n }\n}\n\n\/\/ Client follows the 'users' link\nGET \/api\/users HTTP\/1.1\nAccept: application\/json\n\nHTTP\/1.1 200 OK\nContent-Type: application\/json\n\n{\n \"count\": 2,\n \"users\": [\n {\n \"id\": 123,\n \"name\": \"John Doe\",\n \"_links\": {\n \"self\": { \"href\": \"\/api\/users\/123\" },\n \"orders\": { \"href\": \"\/api\/users\/123\/orders\" }\n }\n },\n {\n \"id\": 456,\n \"name\": \"Jane Smith\",\n \"_links\": {\n \"self\": { \"href\": \"\/api\/users\/456\" },\n \"orders\": { \"href\": \"\/api\/users\/456\/orders\" }\n }\n }\n ],\n \"_links\": {\n \"self\": { \"href\": \"\/api\/users\" },\n \"create\": { \n \"href\": \"\/api\/users\",\n \"method\": \"POST\",\n \"encoding\": \"application\/json\",\n \"schema\": { \"href\": \"\/api\/schemas\/user-create\" }\n }\n }\n}<\/code><\/pre>\nIn this example, the client doesn’t need to know the URL structure in advance. It discovers what it can do through the links provided in each response.<\/p>\n
Media Types for Hypermedia<\/h3>\n
Several standardized formats exist for representing hypermedia controls:<\/p>\n
\n- HAL (Hypertext Application Language)<\/strong>: A simple format that gives a consistent and easy way to hyperlink between resources in your API<\/li>\n
- JSON-LD<\/strong>: A method of encoding linked data using JSON<\/li>\n
- Collection+JSON<\/strong>: A JSON-based read\/write hypermedia-type designed to support management and querying of resource collections<\/li>\n
- Siren<\/strong>: A hypermedia specification for representing entities<\/li>\n<\/ul>\n
Common Problems with “REST” APIs<\/h2>\n
Now that we understand what makes an API truly RESTful, let’s examine common problems with APIs that claim to be RESTful but aren’t:<\/p>\n
1. Ignoring HATEOAS<\/h3>\n
As discussed, most APIs stop at Richardson Maturity Level 2, implementing resources and HTTP verbs but not hypermedia controls. This creates rigid APIs that can’t evolve without breaking clients.<\/p>\n
2. Using URLs as Command Invocations<\/h3>\n
Non-RESTful design often uses URLs as command invocations rather than resource identifiers:<\/p>\n
\/\/ Non-RESTful command-based URL\nGET \/api\/sendEmail?to=user@example.com&subject=Hello\n\n\/\/ RESTful resource-oriented approach\nPOST \/api\/emails HTTP\/1.1\nContent-Type: application\/json\n\n{\n \"to\": \"user@example.com\",\n \"subject\": \"Hello\",\n \"body\": \"Hello, world!\"\n}<\/code><\/pre>\n3. Ignoring HTTP Status Codes<\/h3>\n
Many APIs return 200 OK for everything and put error information in the response body, ignoring the rich set of HTTP status codes designed to convey this information.<\/p>\n
\/\/ Non-RESTful approach\nHTTP\/1.1 200 OK\nContent-Type: application\/json\n\n{\n \"success\": false,\n \"error\": \"Resource not found\",\n \"error_code\": 404\n}\n\n\/\/ RESTful approach\nHTTP\/1.1 404 Not Found\nContent-Type: application\/json\n\n{\n \"message\": \"The requested user with ID 123 was not found\"\n}<\/code><\/pre>\n4. Ignoring HTTP Methods<\/h3>\n
Using only GET and POST methods for all operations is a common anti-pattern:<\/p>\n
\/\/ Non-RESTful approach\nPOST \/api\/users\/123\/delete\n\n\/\/ RESTful approach\nDELETE \/api\/users\/123<\/code><\/pre>\n5. Session-based Authentication<\/h3>\n
Using cookies and sessions for authentication violates the statelessness constraint. Each request should contain all authentication information needed:<\/p>\n
\/\/ Non-RESTful session-based authentication\nPOST \/api\/login HTTP\/1.1\nContent-Type: application\/json\n\n{\n \"username\": \"user\",\n \"password\": \"pass\"\n}\n\n\/\/ Server sets session cookie\nHTTP\/1.1 200 OK\nSet-Cookie: sessionId=abc123; Path=\/; HttpOnly\n\n\/\/ RESTful token-based authentication\nPOST \/api\/tokens HTTP\/1.1\nContent-Type: application\/json\n\n{\n \"username\": \"user\",\n \"password\": \"pass\"\n}\n\nHTTP\/1.1 201 Created\nContent-Type: application\/json\n\n{\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"expires_at\": \"2023-12-31T23:59:59Z\"\n}<\/code><\/pre>\n6. Misusing HTTP Methods<\/h3>\n
Using POST for everything or mismatching methods with their intended use:<\/p>\n
\/\/ Incorrect: Using GET for an operation that changes state\nGET \/api\/users\/123\/deactivate\n\n\/\/ Correct: Using POST or PUT for state changes\nPOST \/api\/users\/123\/actions\/deactivate\n\n\/\/ Or better:\nPUT \/api\/users\/123 HTTP\/1.1\nContent-Type: application\/json\n\n{\n \"status\": \"inactive\"\n}<\/code><\/pre>\n7. Hard-coding URLs in Clients<\/h3>\n
When clients hard-code URLs, it creates tight coupling between client and server, making evolution difficult:<\/p>\n
\/\/ Hard-coded client (problematic)\nfunction getUserOrders(userId) {\n return fetch(`https:\/\/api.example.com\/v1\/users\/${userId}\/orders`);\n}\n\n\/\/ Hypermedia-aware client (flexible)\nasync function getUserOrders(userUrl) {\n \/\/ First, get the user resource\n const userResponse = await fetch(userUrl);\n const userData = await userResponse.json();\n \n \/\/ Find the orders link in the response\n const ordersUrl = userData._links.orders.href;\n \n \/\/ Follow the link to get orders\n return fetch(ordersUrl);\n}<\/code><\/pre>\nBuilding a Better API<\/h2>\n
Now that we understand the common issues, let’s look at how to build a more truly RESTful API:<\/p>\n
1. Start with a Good Resource Model<\/h3>\n
Carefully model your domain as resources. Resources should be nouns, not verbs:<\/p>\n
\n- Good:
\/users<\/code>, \/orders<\/code>, \/products<\/code><\/li>\n- Bad:
\/getUsers<\/code>, \/createOrder<\/code>, \/deleteProduct<\/code><\/li>\n<\/ul>\n2. Use HTTP Methods Properly<\/h3>\n
Match HTTP methods to their intended semantics:<\/p>\n
\n- GET<\/strong>: Retrieve a resource (safe, idempotent)<\/li>\n
- POST<\/strong>: Create a new resource or submit data for processing<\/li>\n
- PUT<\/strong>: Update a resource by replacing it entirely (idempotent)<\/li>\n
- PATCH<\/strong>: Update a resource partially (not necessarily idempotent)<\/li>\n
- DELETE<\/strong>: Remove a resource (idempotent)<\/li>\n
- HEAD<\/strong>: Like GET but returns only headers (safe, idempotent)<\/li>\n
- OPTIONS<\/strong>: Get information about available communication options (safe)<\/li>\n<\/ul>\n
3. Use Appropriate Status Codes<\/h3>\n
Use HTTP status codes to communicate outcomes:<\/p>\n
\n- 2xx<\/strong>: Success (200 OK, 201 Created, 204 No Content)<\/li>\n
- 3xx<\/strong>: Redirection (301 Moved Permanently, 304 Not Modified)<\/li>\n
- 4xx<\/strong>: Client errors (400 Bad Request, 401 Unauthorized, 404 Not Found)<\/li>\n
- 5xx<\/strong>: Server errors (500 Internal Server Error, 503 Service Unavailable)<\/li>\n<\/ul>\n
4. Implement HATEOAS<\/h3>\n
Include hypermedia controls in your responses. You can start with a simple approach:<\/p>\n
HTTP\/1.1 200 OK\nContent-Type: application\/json\n\n{\n \"id\": 123,\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"_links\": {\n \"self\": { \"href\": \"\/api\/users\/123\" },\n \"edit\": { \"href\": \"\/api\/users\/123\", \"method\": \"PUT\" },\n \"friends\": { \"href\": \"\/api\/users\/123\/friends\" },\n \"profile-image\": { \"href\": \"\/api\/users\/123\/profile-image\" }\n }\n}<\/code><\/pre>\n5. Use Content Negotiation<\/h3>\n
Support different representations of your resources based on the client’s needs:<\/p>\n
\/\/ Client requests JSON\nGET \/api\/users\/123 HTTP\/1.1\nAccept: application\/json\n\n\/\/ Client requests XML\nGET \/api\/users\/123 HTTP\/1.1\nAccept: application\/xml<\/code><\/pre>\n6. Implement Stateless Authentication<\/h3>\n
Use token-based authentication like JWT (JSON Web Tokens) instead of sessions:<\/p>\n
GET \/api\/users\/123 HTTP\/1.1\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...<\/code><\/pre>\n7. Enable Caching<\/h3>\n
Use HTTP caching mechanisms to improve performance:<\/p>\n
HTTP\/1.1 200 OK\nCache-Control: max-age=3600\nETag: \"33a64df551425fcc55e4d42a148795d9f25f89d4\"\nLast-Modified: Wed, 21 Oct 2023 07:28:00 GMT\nContent-Type: application\/json\n\n{\n \"id\": 123,\n \"name\": \"John Doe\"\n}<\/code><\/pre>\n8. Document Your Media Types<\/h3>\n
If you’re using custom media types, document their structure and semantics:<\/p>\n
GET \/api\/users\/123 HTTP\/1.1\nAccept: application\/vnd.example.user+json\n\nHTTP\/1.1 200 OK\nContent-Type: application\/vnd.example.user+json\n...<\/code><\/pre>\n9. Provide an API Entry Point<\/h3>\n
Give clients a single entry point to discover your API:<\/p>\n
GET \/api HTTP\/1.1\nAccept: application\/json\n\nHTTP\/1.1 200 OK\nContent-Type: application\/json\n\n{\n \"version\": \"1.0\",\n \"_links\": {\n \"users\": { \"href\": \"\/api\/users\" },\n \"products\": { \"href\": \"\/api\/products\" },\n \"documentation\": { \"href\": \"\/api\/docs\" }\n }\n}<\/code><\/pre>\nWhen NOT to Use REST<\/h2>\n
While REST is powerful, it’s not the best solution for every API. Consider alternatives when:<\/p>\n
1. You Need Real-time Communication<\/h3>\n
For real-time applications, consider WebSockets or Server-Sent Events:<\/p>\n
\/\/ WebSocket example\nconst socket = new WebSocket('wss:\/\/api.example.com\/ws');\nsocket.onmessage = (event) => {\n const data = JSON.parse(event.data);\n console.log('Received:', data);\n};<\/code><\/pre>\n2. You Need Complex Queries<\/h3>\n
For complex data requirements, consider GraphQL:<\/p>\n
\/\/ GraphQL query example\nconst query = `\n query {\n user(id: \"123\") {\n name\n email\n friends {\n name\n email\n }\n orders(status: \"COMPLETED\") {\n id\n total\n items {\n product {\n name\n price\n }\n quantity\n }\n }\n }\n }\n`;<\/code><\/pre>\n3. You Need Remote Procedure Calls<\/h3>\n
For RPC-style interactions, consider gRPC or JSON-RPC:<\/p>\n
\/\/ JSON-RPC example\n{\n \"jsonrpc\": \"2.0\",\n \"method\": \"calculateTax\",\n \"params\": {\n \"amount\": 100,\n \"category\": \"food\",\n \"location\": \"CA\"\n },\n \"id\": 1\n}<\/code><\/pre>\n4. You Have Limited Resources<\/h3>\n
For constrained environments (IoT, microcontrollers), consider lightweight protocols like MQTT or CoAP.<\/p>\n
Conclusion<\/h2>\n
While many APIs claim to be RESTful, most only implement a subset of REST principles, missing key constraints like hypermedia and proper resource modeling. True REST goes beyond HTTP methods and JSON responses to create self-describing, evolvable APIs that can change without breaking clients.<\/p>\n
Creating a truly RESTful API requires more upfront investment but pays dividends in flexibility, discoverability, and maintainability. That said, REST isn’t always the right choice. Consider your specific requirements and constraints before choosing an architectural style.<\/p>\n
Whether you decide to go fully RESTful or opt for a pragmatic approach that borrows some REST principles, understanding the true definition of REST will help you make more informed API design decisions.<\/p>\n
Remember, the goal isn’t to achieve perfect REST compliance for its own sake, but to create APIs that serve your users’ needs while remaining flexible, scalable, and maintainable over time.<\/p>\n
When designing your next API, consider how many of the REST constraints you’re actually implementing, and whether a different architectural style might better serve your specific use case.<\/p>\n","protected":false},"excerpt":{"rendered":"
In the world of web development, we often hear terms like “REST API” thrown around casually. Many developers claim to…<\/p>\n","protected":false},"author":1,"featured_media":7435,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[23],"tags":[],"class_list":["post-7436","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-problem-solving"],"_links":{"self":[{"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/posts\/7436"}],"collection":[{"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/comments?post=7436"}],"version-history":[{"count":0,"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/posts\/7436\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/media\/7435"}],"wp:attachment":[{"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/media?parent=7436"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/categories?post=7436"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/algocademy.com\/blog\/wp-json\/wp\/v2\/tags?post=7436"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}