Hierarchical resource paths in Rest API

Introduction

Hierarchical resource paths help organize and access related data in a clear, logical way. They show how resources connect like folders in a file system.

When you want to access a specific item inside a collection, like a single book in a library.

When you need to show relationships, such as comments belonging to a blog post.

When designing APIs that reflect real-world nested data, like users and their orders.

When you want URLs that are easy to read and understand by humans.

When you want to keep your API organized and scalable as it grows.

Syntax

Rest API

/resource1/{id1}/resource2/{id2}/resource3

Each part separated by slashes represents a level in the hierarchy.

Curly braces {} show variable parts, like IDs.

Examples

Access order 456 that belongs to user 123.

Rest API

/users/123/orders/456

Get book 42 inside library 5.

Rest API

/libraries/5/books/42

List all employees in department 3 of company 7.

Rest API

/companies/7/departments/3/employees

Sample Program

This example shows a hierarchical path to get a specific comment. It starts from the user, then the post, then the comment.

Rest API

GET /users/42/posts/10/comments/5

# This request fetches comment 5 on post 10 by user 42.

Important Notes

Keep paths simple and consistent for easier use.

Use nouns for resources, not verbs.

Hierarchical paths help with permissions and filtering data logically.

Summary

Hierarchical resource paths organize data like folders inside folders.

They use slashes and IDs to show relationships clearly.

This makes APIs easier to understand and use.