What are best practices for REST nested resources?

by

I’ve tried both design strategies – nested and non-nested endpoints. I’ve found that:

  1. if the nested resource has a primary key and you don’t have its parent primary key, the nested structure requires you to get it, even though the system doesn’t actually require it.

  2. nested endpoints typically require redundant endpoints. In other words, you will more often than not, need the additional /employees endpoint so you can get a list of employees across departments. If you have /employees, what exactly does /companies/departments/employees buy you?

  3. nesting endpoints don’t evolve as nicely. E.g. you might not need to search for employees now but you might later and if you have a nested structure, you have no choice but to add another endpoint. With a non-nested design, you just add more parameters, which is simpler.

  4. sometimes a resource could have multiple types of parents. Resulting in multiple endpoints all returning the same resource.

  5. redundant endpoints makes the docs harder to write and also makes the api harder to learn.

In short, the non-nested design seems to allow a more flexible and simpler endpoint schema.

More Related Contents:

  1. What is the proper REST response code for a valid request but an empty data?
  2. When do I use path params vs. query params in a RESTful API?
  3. API pagination best practices
  4. Delete multiple records using REST
  5. Call a Server-side Method on a Resource in a RESTful Way
  6. RESTful Authentication
  7. RESTful URL design for search
  8. How can I handle many-to-many relationships in a RESTful API?
  9. How to version REST URIs
  10. HTTP response code for POST when resource already exists
  11. XDebug and RESTful server using PHPStorm or POSTman
  12. REST Complex/Composite/Nested Resources [closed]
  13. What is REST? Slightly confused [closed]
  14. Transactions across REST microservices?
  15. Designing URI for current logged in user in REST applications
  16. RESTful Services – WSDL Equivalent
  17. Unable to upload zip file through karate framework
  18. What’s the best RESTful method to return total number of items in an object?
  19. Firefox Add-on RESTclient – How to input POST parameters?
  20. Spring 4 RestController JSON: characteristics not acceptable according to the request “accept” headers
  21. Jersey with Struts2 [duplicate]
  22. REST API Authentication
  23. Should I use Singular or Plural name convention for REST resources?
  24. How to download excel (.xls) file from API in postman?
  25. Where can I find jenkins restful api reference? [closed]
  26. Is it correct to return 404 when a REST resource is not found?
  27. When is it appropriate to respond with a HTTP 412 error?
  28. When in my REST API should I use an envelope? If I use it in one place, should I always use it?
  29. Swagger UI passing authentication token to API call in header
  30. REST API DESIGN – Getting a resource through REST with different parameters but same url pattern

Leave a Comment