I am designing an API and I need input on the design.

Consider this use case where we have Schools & Students:

We want to create reports based on the performance of students in previous exams.

Now I can choose to generate a report based on the following parameters:

1. School Name (All students in the specified school)
2. ZIP code (All students in the specified ZIP code)
3. Student ID (Single student specified by ID)
4. Student standard (Student studying only in the specified standard)

Should I have 4 separate POST endpoints for this purpose or one common endpoint which chooses which flow to use after validating the payload?

CodePudding user response：

I would choose 4 different endpoints. I find it simpler to document the API and to write a client for multiple different endpoints because all of them will have only a single acceptable message body format.

CodePudding user response：

I agree a lot with @inf3rno's answer but I would add a counter point in favor of a single endpoint in that, if the functionality is very similar, it might be worth just having a single endpoint and adding a query parameter to specify the type of report e.g. /report?type=zip.

You could then document it almost as well as four separate endpoints without having to actually make four endpoints.