What is REST?

What is a resource?

What are hierarchical resource structures?

Best practices for designing hierarchical resource structures

1. Use Nouns in URI

   REST APIs should be designed for resources that can be entities, services, etc. Therefore, they must always be nouns. Suppose the client is asking to add resource to the collection, we can use the following request:

   Correct -> post /comments
   Wrong -> post /createComments
2. Plurals or Singulars

   Generally, it is recommended to use plurals. But there is no hard rule that one cannot use singular for a REST API resource name. The ideology behind using plurals is that we are operating on one resource from a collection of resources. To depict a collection, we use plurals. Suppose the client is asking to retrieve a resource with the resource ID 123 from a collection of resources, the HTTP request should look like something below: GET /comments/123 To add one resource to the current collection of resources, we may use the following HTTP request: POST /comments This makes your API more consistent, intuitive, and easy to understand.

3. Hierarchical URLs

   Hierarchical URLs in RESTful APIs provide a consistent and structured way to organize resources. Just like folders in a computer's file system, hierarchical URLs arrange resources in a logical order, making them easy to find and understand.

   Consider the following example. This clearly shows the parent-child relationship between posts and comments.

   Root Resource:

   URL: https://api.example.com/blog
   Description: The base URL for the blog API, serving as the entry point to access various resources.

   Posts Resource:

   URL: https://api.example.com/blog/posts
   Description: Description: Represents the collection of blog posts.

   Single Post Resource:

   URL: https://api.example.com/blog/posts/123
   Description: Represents an individual blog post with an ID of 123.

   Comments Resource:

   URL: https://api.example.com/blog/posts/123/comments
   Description: Represents the collection of comments for the blog post with ID 123.

   Single Comment Resource:

   URL: https://api.example.com/blog/posts/123/comments/456
   Description: Represents an individual comment with an ID of 456 for the blog post with ID 123.
4. HTTP Verbs

   HTTP verbs are the actions that can be performed on resources in a RESTful API. They define the type of operation being requested by the client. Here's a brief explanation of the commonly used HTTP verbs:

   GET: Used to retrieve data from a specified resource. When a client sends a GET request to the server, it expects to receive data without causing any side effects on the server.
   POST: Used to submit data to a specified resource. It is commonly used for creating new resources or submitting form data to the server. A POST request may result in the creation of a new resource on the server.
   PUT: Used to update a resource or create a new resource if it does not exist. When a client sends a PUT request, it typically includes the full representation of the resource being updated or created.
   DELETE: Used to remove a specified resource from the server. It is used when the client wants to delete the specified resource permanently.
   PATCH: Used to apply partial modifications to a resource. It is similar to PUT, but instead of providing the full representation of the resource, the client sends only the changes that need to be applied.
   HEAD: Similar to GET, but it only retrieves the headers of the response without the body. It is often used to check the status of a resource or to retrieve metadata about a resource without downloading the entire content.
   OPTIONS: Used to retrieve the HTTP methods that are supported by a resource. It is often used by clients to determine the capabilities of a server or to check the CORS (Cross-Origin Resource Sharing) policy.

   URL	HTTP Verb	Purpose
   /blog/posts	GET	Retrieves a list of all blog posts.
   /blog/posts	POST	Creates a new blog post.
   /blog/posts/123	GET	Retrieves the details of the blog post with ID 123.
   /blog/posts/123	PUT/PATCH	Updates the content of the blog post with ID 123.
   /blog/posts/123	DELETE	Deletes the blog post with ID 123.
   /blog/posts/123/comments	GET	Retrieves a list of all comments for the blog post with ID 123.
   /blog/posts/123/comments	POST	Adds a new comment to the blog post with ID 123.
   /blog/posts/123/comments/456	GET	Retrieves the details of the comment with ID 456 for the blog post.
   /blog/posts/123/comments/456	PUT/PATCH	Updates the content of the comment with ID 456 for the blog post.
   /blog/posts/123/comments/456	DELETE	Deletes the comment with ID 456 for the blog post.

5. Pagination for Large Collections

   Pagination is a technique used in web development to manage large collections of data by splitting them into smaller, more manageable chunks or pages. In the context of RESTful APIs, pagination is particularly important when dealing with resources that may return a large number of results in a single request.
   When the client wants to fetch comments from a post, the client can implement
   pagination by using query parameters like page and limit.
   /posts/1234/comments?page=2&limit=10
   This will fetch the second page with 10 comments per page.

6. Filtering with Query Parameters

   Filtering with query parameters in RESTful APIs allows clients to retrieve specific subsets of resources based on certain criteria. This provides flexibility and customization options for clients, allowing them to tailor API responses to their specific needs without requiring additional endpoints or complex query languages.
   To filter posts based on a specific category, use a query parameter like
   /posts?category=technology to retrieve all posts in the technology category.

Best practices for managing relationships

1. Resource Embedding

   Resource embedding involves including related resources directly within the representation of a parent resource in API responses. This approach can help reduce the number of requests required to retrieve all necessary data, as clients receive complete information about related resources in a single response.
   Consider a blog API where each post can have multiple comments. When retrieving a specific post , the server embeds the comments directly within the post representation in the API response.
   GET /posts/1234

   Response:
   {
   "id": 1234,
   "title": "Getting Started with RESTful APIs",
   "content": "Lorem ipsum dolor sit amet...",
   "comments": [
   {
   "id": 1,
   "text": "Great article!",
   "author": "John Doe"
   },
   {
   "id": 2,
   "text": "Very informative!",
   "author": "Jane Smith
   }
   ]
   }

2. Using Resource Identifiers

   Instead of embedding all comment details within a post response, use unique identifiers to represent relationships. This makes your API more modular, maintainable, and efficient, as you can fetch, update, or delete each resource independently, and avoid sending or receiving unnecessary data.
   For example, instead of using /posts/{id} with a nested array of comments, use /posts/{id}/comments with an array of comment ids.
   GET /posts/1234

   Response:
   {
   "id": 1234,
   "title": "Getting Started with RESTful APIs",
   "content": "Lorem ipsum dolor sit amet...",
   "comments": [1, 2, 3]
   }
   }

Conclusion