REST vs RESTful API: What's the difference?
The key difference between the terms REST versus RESTful is that REST refers to a philosophy about the architecture and design of web services, while the term RESTful refers to any API that properly implements the REST philosophy.
What is REST?
The term REST, which stands for representational state transfer, was coined by Roy Fielding in his 2000 doctoral dissertation about how clients and servers should communicate with each other across a network.
At the heart of REST are the following six core principles, or as they are more technically called, REST constraints:
- Request-response cycles should be stateless.
- A well-defined interface separates client to server request-response cycles.
- A layered system architecture hides any back-end implementations from the client.
- Servers should inform clients about cacheable responses to help optimize performance.
- Servers should offload complex processing to clients by asking them to run code on demand.
- APIs are invoked through a uniform interface that references resources through URIs and operations through HTTP methods.
The italicized words in the numbered principles are the abbreviated terms often used to refer to the six RESTful constraints.
REST and RESTful APIs
A RESTful API should conform as much as possible to the six REST constraints. It certainly should not violate them.
A problem that developers and architects often encounter with RESTful APIs is that the six REST constraints, especially the demand to use a uniform interface, can be highly nuanced and challenging to fully implement.
Nouns, verbs and well-formed URIs
At the very least, a RESTful API respects REST's uniform interface constraint in two ways:
- Using nouns in RESTful URIs to ensure web service operations work on resources.
- Using the HTTP verbs properly to perform operations on resources.
Compliance with resource-focused, RESTful URL naming conventions is fairly easy to accomplish: Use nouns as endpoints in your URIs. However, using HTTP verbs properly is a bit more complicated.
For example, to retrieve or delete a resource through a RESTful API, use the GET and DELETE HTTP verbs. However, the proper use of other HTTP methods can be a challenge. For example:
- PUT operations can idempotently create or save known resources.
- POST operations can update or save resources but is not idempotent.
- PATCH operations can idempotently update a known resource.
Running afoul of these nuanced rules about PUT, POST and PATCH operations would put into question just how RESTful your API really is.
HATEOAS for full REST compliance
Furthermore, REST and the uniform interface constraint demands support for HATEOAS (hypermedia as the engine of application state), which is rarely implemented.
HATEOAS insists that when a resource representation is delivered to a client, so must be the various URIs that can be invoked to perform subsequent operations on the resource.
Technically speaking, a RESTful API must implement HATEOAS to fully comply with the REST constraints. This rarely occurs, though, and most people still consider an API RESTful even if it does not implement the principles of HATEOAS.
When is a REST API RESTful?
It's rare for a RESTful API or web service to fully comply with REST's six architectural constraints. However, most solution architects strive to respect the HTTP protocol's methods. They use resource-based URLs, and create stateless and cacheable endpoints that enable loose coupling between the client and the server.
If you attain this threshold, your APIs will be easily understood and consumed by others, which is typically the main goal when creating web services. Most people will consider your APIs RESTful -- although Roy Fielding might raise an eyebrow.
Karan Adapala is a full-stack developer, app architect and cloud enthusiast with expertise in React, Node.js, TypeScript, Python, Docker, Terraform, Jenkins and Git.