Representing resources in RESTful API

Question

I have a database of surveys responses and I'm trying to build a RESTful API to expose this data. API should be able to return the following information:

Available surveys
Questions
Answers
Report (sum of responses for every type of answer per survey question)

I have a problem with identifying how should the resources be structured in this case.

For surveys, questions and responses it's fairly simple:

GET /surveys
GET /questions // filter by surveyId possible
GET /responses // filter by questionId and SurveyId possible

What would be the best approach to fit the reports in this structure? Do I set up a separate route, e.g.:

GET /reports/responses-by-question?surveyId=1

or do I add it as next level in the responses path? E.g.

GET /responses/by-question?surveyId=1

Or do I get this completely wrong and there's some better approach?

How about surveys/1/reports to get all reports for a survey? — horatius
– horatius, Commented Aug 7, 2018 at 13:01
I was thinking about it, but the report calculates the responses, not surveys, hence it doesn't seem logical to me... But maybe I'm overcomplicating this. — rufus1530
– rufus1530, Commented Aug 7, 2018 at 13:07

dkulkarni · Accepted Answer · 2018-08-07 13:04:27Z

1

Keeping the survey as the first class citizen, I would structure it like so

GET /surveys: Get all surveys
GET /surveys/<surveyId>/questions: Get questions for a survey.
GET /surveys/<surveyId>/questions/<questionId>/answers: Get answers for a survey question.
GET /surveys/<surveyId>/reports: Get report for a survey.

Note: If you think reports are going to be filtered by multiple paramaters, you could consider making it a search end point.

GET /surveys/<surveyId>/reports?questionId=<questionId>

answered Aug 7, 2018 at 13:04

dkulkarni

2,8304 gold badges29 silver badges36 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

rufus1530 Over a year ago

I like it, looks very elegant. Do you know any good guides on how to determine first class citizens in such situations?

dkulkarni Over a year ago

That's more to do with how you design your domain entities for the service you're building. For example, if you're designing an order management system, it's likely an Order is the first class citizen.

dkulkarni Over a year ago

Also, here's a video you may find useful: youtube.com/watch?v=U6CeaA-Phqo

Collectives™ on Stack Overflow

Representing resources in RESTful API

1 Answer 1

3 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

3 Comments

Your Answer

Sign up or log in

Post as a guest

Related