I would utilize nested routes to represent the hierarchy of the resource. For example, I might structure the endpoints as /categories/{categoryId}/subcategories/{subcategoryId}/products. This approach helps maintain clarity and allows clients to easily understand the relationship between the resources.
In depth
A hierarchical resource design is essential for representing complex relationships in a REST API. By using nested routes, we provide a clear and intuitive structure that reflects the natural hierarchy of the data. Furthermore, this design can enhance filtering capabilities, as clients can request products belonging to specific subcategories with a straightforward URL. It’s important to ensure that the API remains flexible. For instance, we would need to consider potential changes in the hierarchy, such as category reorganization or merging, and design endpoints that can accommodate these changes without breaking existing clients. Additionally, to support efficient querying, we may implement pagination and filtering directly in the endpoints to limit payload sizes and improve performance.
Example scenario
In a previous project, we designed an e-commerce API with a hierarchical product catalog. The endpoints were structured as /categories/{categoryId}/subcategories/{subcategoryId}/products. This setup allowed frontend teams to easily fetch all products under a specific subcategory while maintaining a clear understanding of the catalog structure. We also implemented caching strategies to optimize response times when accessing frequently requested subcategories.
Common mistakes
One common mistake is over-nesting routes, which can lead to overly complex URLs and make the API difficult to consume. For example, having too many layers like /countries/{countryId}/states/{stateId}/cities/{cityId}/products can create confusion. Another frequent error is neglecting to account for changes in the hierarchy, which could break existing clients if not handled correctly. It's crucial to design with future changes in mind, allowing for backward compatibility.
Follow-up questions
- How would you handle changes in the resource hierarchy without breaking existing clients?
- What considerations would you make for versioning your API?
- Can you discuss how you would implement caching for such a hierarchical structure?
- How might you document this API structure for external developers?
Preparing for a system design interview?
- A 7-step method for answering any system design question, plus estimation numbers
- 5 worked designs: URL shortener, rate limiter, chat, news feed and file storage
- Guides to caching, databases, queues, consistency and reliability, with a 4-week study plan
- 306 practice questions with answers on caching, databases, queues, microservices, APIs and more
5 worked designs, a 4-week plan and 306 practice questions with answers.
The material stays free to read online. This is the organised, offline, print-ready PDF edition. Secure payment by PayPal; your personal download link is emailed after payment is confirmed. Digital product, no shipping.
