REST (Representational State Transfer) is an architectural style for building APIs that rely on HTTP requests to access and use data. A REST API breaks down an application into logical resources that expose endpoints which can be accessed with HTTP requests. So what exactly constitutes a resource in REST APIs?
Resources in REST APIs
A resource is an object or representation of something that has an identity. Resources in REST APIs are identified by URIs/URLs. For example, in an API for a blog application, some resources would be:
- Individual blog posts
- A list of blog posts
- Authors
- Comments
So a resource could be a blog post, all blog posts, authors, comments, etc. Each resource has a URI that uniquely identifies it. For example:
- /posts – retrieve all posts
- /posts/123 – retrieve post with id 123
- /authors – retrieve all authors
- /authors/456 – retrieve author with id 456
- /posts/123/comments – retrieve comments for post 123
Resources in a REST API are modeled as objects, which have data, relationships to other resources, methods that operate on them, and more. Resources model entities in an application and expose data and functionality for clients to access and manipulate.
Types of Resources
There are two main types of resources in REST APIs:
Individual Resources
These represent a single object or entity. For example, a single blog post or author. Individual resources have their own URI that identifies that specific resource, like /posts/123 for post with id 123. Operations like GET, POST, PUT, PATCH, and DELETE work on individual resources.
Collection Resources
These represent a group or collection of individual resources. For example, /posts would represent all blog posts. Collection resources allow for queries and filtering to handle sets of resources. Operations like GET and POST work on collection resources.
Resource Relationships
Resources in a REST API also define relationships between each other. There are two main types of relationships:
One-to-Many Relationship
One resource is related to many other resources. For example, one author has many posts. The URI to get all posts for an author could be /authors/123/posts.
Many-to-One Relationship
Many resources are related to one resource. For example, many comments belong to one post. The URI /posts/123/comments gets all comments for post 123.
Defining relationships between resources allows navigation across the API by following links between related resources.
Resource Representations
Resources send representations in response to requests. A representation is data formatted in some way, typically JSON or XML, that represents the state of the resource. For example, a GET request to /posts/123 would return a JSON representation of that blog post resource.
The representation contains properties or fields that describe the resource state. Different representations could be sent for different scenarios:
- Full detailed representation for a single GET request
- Summary view for a collection GET request
- Small subset of fields for an update PATCH request
The client and server agree on the data format and structure of representations at runtime based on request headers like Accept and Content-Type.
Resources and HTTP Methods
REST APIs access and manipulate resources using the standard HTTP methods:
HTTP Method | API Use |
---|---|
GET | Retrieve a representation of a resource |
POST | Create a new resource |
PUT | Update a resource |
PATCH | Partial update of a resource |
DELETE | Delete a resource |
This basic set of operations provide everything needed for robust CRUD (create, read, update, delete) functionality and help enforce a uniform interface for manipulating resources.
Best Practices for REST Resources
Here are some best practices when modeling resources for a REST API:
- Use plural nouns for collection resource URIs like /posts
- Use HTTP methods explicitly – GET for read, POST for create, PUT/PATCH for update, DELETE to delete
- Use lowercase letters in URIs
- Use hyphens – to separate words in URIs
- Avoid unnecessary nesting of resources in URIs
- Define logical hierarchical relationships between resources
- Send full representations after POST and sparse representations after PATCH
- Use HATEOAS links to enable navigation through representations
Common Issues with Resources
Some common issues that can occur when modeling resources:
- Treating a single resource as multiple resources. For example, having separate URIs like /posts and /post.
- Using actions or verbs in URIs like /posts/delete/123 instead of just /posts/123
- Nested resources too many levels deep making URIs long and confusing
- Inconsistent or non-plural naming like /Post/123 and /Posts for collections
- Not using HTTP methods properly – using GET for an operation that should be DELETE
- Using status codes incorrectly – 200 OK for a DELETE instead of 204 No Content
Conclusion
Resources are at the core of REST API design. Resources represent entities, have unique IDs, relationships, and defined ways of interacting with them using HTTP methods. Defining resources correctly provides a powerful way to model and expose application data and functionality to clients. Keeping resources focused, properly using HTTP, and thinking about consumption by client developers helps create clean, usable REST APIs.