Which routes to pick for REST API? [closed] - api

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I'm developing a restful API using NodeJS. To give you a little more insight in my application:
My application has surveys. A survey contains questions which in their turn has choices.
To add a question, you need to provide the id of the survey in the body of the post. To add an option, you need to provide the id of the question.
Now for the API routes. What would be better:
Option 1
/api/departments
/api/surveys
/api/questions
/api/choices
Option 2
/api/departments
/api/departments/department_id/surveys
/api/departments/department_id/surveys/survey_id/questions
/api/departments/department_id/surveys/survey_id/questions/question_id/options
The last one seems more logical because I don't need to provide the id of the parent in the body of the post.
What is best practice to use as endpoints?

Answer 1

I don't think there's a "best practice" between the two; rather, it's about having the interface that makes the most sense for your application. #2 makes the most sense if you're typically going to access the surveys on a per-department basis, and also makes sense in terms of accessing questions on a per-survey basis. If you wanted to eliminate the per-department part, you'd do something that's kind of a mix of the above:
/api/departments
/api/surveys
/api/surveys/survey_id/questions
/api/surveys/survey_id/questions/question_id/options
If you DO want to go by per-department, I'd change #2 so that instead of /api/departments/surveys one would access /api/departments/department_id/surveys ...
But without knowing more about the application, it's difficult to know what the best answer is.

Answer 2

Do surveys contain anything besides questions? do questions contain anything besides choices? The reason I ask is that if the answer to both is no then I'd actually prefer something like this:
/api/departments/ # returns a list of departments
/api/departments/<survey-id>/ # returns a list of questions
/api/departments/<survey-id>/<question-id>/ # returns a list of choices
/api/departments/<survey-id>/<question-id>/<choice-id> # returns a list of options
or something to that effect. Basically, I like to keep the concept of "containers" and "data" rigid. I like to think of it like a file system.
So if the concept ends in an "s", it's a container (and I'd like the route to end with a "/" to indicate that it acts like a folder, but that's a nit).
Any access to "/" results in the element at that index, which of course can be another container. Similar to directory structure in a file system. For example, if I were to lay these out in a file system, I might come up with something like this:
+ /api/departments/
|-----------------/human-resources/
|---------------/survery-10/
|----------/choice-10

Answer 3

The choice depends on whether resources are owned or shared by higher-level resources; whether you want cascading delete or not. If owned (with cascading delete), choose option 2 and if shared, choose option 1.
If a survey is deleted, I guess you want to delete all questions and options with it (cascading delete). This matches well with option 2, because if you delete resource /api/departments/departmentid/surveys/surveyid, you naturally also delete all subresources /api/departments/departmentid/surveys/surveyid/questions/....
On the other hand, if you want the option to share questions among multiple surveys and share surveys among multiple departments, then option 1 is better.
Of course, you can also have a mix of option 1 and option 2, if some resource types are owned and others are shared.