带资源和深度资源的REST API设计

Question

While designing an API which will have a resource and a deep resource (/resource/{id}/deepResource), Is it a good design to have the deepResource as a parameter in resource path when there are numerous dynamic deepResources?

For example: A post request to create a new resource under a section of main resource

POST: /accounts/{id}/{section}

{section} can be any deep resource under account like "comment", "service request", "checkbook request" etc.

The idea is {section} can grow as the application grows. So instead of having multiple endpoints for each deep resource like /accounts/{id}/comment

/accounts/{id}/service

/accounts/{id}/checks

how about having /accounts/{id}/{section}?

Logic on the backend is handled accordingly for each deep resource that gets added in future.

Appreciate your insights.

Answer 1

how about having /accounts/{id}/{section}?

If that works for you, go right ahead.

REST doesn't care how you implement your back end.

REST also doesn't care how you construct your resource identifiers. Whether you use a URI template with one parameter, or two parameters, or no parameter at all, no longer matters once you've copied the request-target into the HTTP request.

In some API description languages (swagger/openapi, jsonapi, etc) you may find it difficult to describe the nuances of the different sections, especially in cases where "comment", "service", "checks" have different content-types, different schemas, and so on.