Why are multiple endpoints bad for REST API?
Multiple endpoints increase the effort for the API owner to document the whole thing and make onboarding for new customers much more troublesome. Multiple endpoints that return the same representations can also lead to problems with caching and can violate one of the core principles of RESTful API design.
Do you have to use nested resources in REST API?
While nesting is sometimes necessary and can’t be avoided, it is often a choice that comes with specific costs or dangers we should keep in mind. Let’s look at them one-by-one. We learned before that nesting resources could make our URLs more readable, but this isn’t a sure bet.
How are representations returned in a REST API?
Multiple endpoints that return the same representations can also lead to problems with caching and can violate one of the core principles of RESTful API design. This problem can be solved via HTTP redirects, so all representations are returned from a central root resource and can be cached, but there is still code needed to implement this.
Why are sub resources also called sub resources?
One topic in this space that is debated quite often is the nesting of resources also called sub-resources. Why would anyone nest their resources? Are they a good idea in the first place? Should we nest our resources? When should we nest our resources? If we nest our resources, what should we keep in mind?
What should the nesting depth be in a REST API?
So when we start to go down this path, we should step back sometimes and look if we are still accomplishing our goal of improved readability. A rule of thumb is a maximum nesting depth of two. Sometimes a depth of three is also okay. For example, if our IDs are short and easily readable.
Which is an example of a good REST API?
If you know the house has number 42, but you don’t remember the street it doesn’t help you much. Another example could be file-names in a file-system. Just knowing that our file is called README.md won’t help if there are hundreds of files named like that in hundreds of different directories.