REST (Representational State Transfer) is an architectural style for designing web services. At the core of REST is the concept of resources. But what exactly is a resource in REST?
What is a Resource in REST?
A resource is a key abstraction of information in REST. A resource is an object or representation of something, which has some associated data with it and there can be set of methods to operate on it. Resources are accessed using URIs.
Some examples of resources:
- A document or file
- A temporal service or collection of other resources
- A collection of other resources
- A non-virtual object (e.g. a person)
So in summary, a resource is an object or representation of something that has associated data with it. It is a key abstraction of information in REST.
Resources in REST have a Uniform Interface
A key aspect of resources in REST is that they all share a uniform interface. This means that resources are manipulated in the same way no matter what they actually represent. The uniform interface consists of:
- Resource identification through URIs – e.g. https://api.example.com/users
- Representation through serialization formats like JSON and XML
- Self-descriptive messages through headers, status codes and hypermedia
- Stateless client-server communication
This uniform interface simplifies the overall REST architecture and decouples the client and server sides of the architecture.
Resources as Nouns
Resources are nouns, not verbs. They represent objects, data or services – not actions. Here are some examples of resources as nouns:
- /users
- /articles/123
- /stocks/AAPL
And here are some examples of actions which are NOT good resource names:
- /updateUser
- /saveArticle
- /buyStock
- /printDocument
Using only nouns keeps the REST interface consistent and helps decouple clients and servers.
Resource Representations
Resources can have multiple representations. For example, a resource representing a blog post might have an HTML, JSON and XML representation. When a client requests a resource, it can specify which representation it wants in the HTTP headers using content negotiation.
Some common representation formats:
- JSON (JavaScript Object Notation)
- XML (Extensible Markup Language)
- HTML (HyperText Markup Language)
- Plain text
- JPEG, PNG, GIF (images)
Allowing multiple representations makes REST services flexible and decouples clients from servers. New representations can be added without breaking existing clients.
Resources Share Common Manipulation Methods
REST resources share a common set of manipulation methods, as defined by the HTTP protocol:
| Method | Action |
|---|---|
| GET | Fetch the current state of the resource |
| POST | Create a new resource |
| PUT | Update the existing resource |
| PATCH | Partially update the resource |
| DELETE | Delete the resource |
This standard set of methods further encourages the uniform interface between clients and servers.
Resources Can Be Related
Resources don’t exist in isolation. They are often related to other resources. Some common ways resources can be related:
- One resource contains another resource (nesting)
- One resource references another resource (linking)
- One resource has metadata about another resource
For example, an article resource might contain author and comment resources. Or a user resource might link to article resources written by that user.
These relationships between resources reflect how they are related in reality. The separation encourages loose coupling between resources.
Resources Can Link To Other Resources
Resources can contain links to other related resources. This is enabled by hypermedia formats like HTML, HAL or JSON-LD which allow embedding links.
For example, an article resource representation might include links to the author resource and the publication resource it belongs to. The links enable clients to directly navigate to other related resources.
This technique removes the need for clients to hardcode URIs and keeps them decoupled from backend server changes.
Conclusion
To summarize:
- A resource is an object or representation of something with associated data
- Resources have a uniform interface for manipulation via HTTP methods
- Resources are represented in formats like JSON, XML and HTML
- Resources can be related to each other
- Resources can link to other resources via hypermedia
The resource abstraction is at the core of REST. Resources decouple clients from servers, encourageloose coupling between resources and enable resources to be manipulated through a standard uniforminterface. All of this makes building and evolving RESTful APIs easier over time.