I refer to this fantastic answer to an earlier question I had.
My question is, say you have an endpoint
GET /tasks and that endpoint accepts query params to get certain groupings of data like:
As a consumer of this API I can use these query params to then derive statistics like:
- How many high priority tasks are currently open?
- For the month of January, what was the mean time to complete a task?
Now the problem is, if I want derive statistics like 'mean time to complete a task, across all time' I'm going to need to pull in every single item just to make that calculation.
I figure that instead the backend could be calculating and storing these statistics on a separate table, and it can update that table as resources change, or cache queries as they occur.
The question is - is it appropriate to use the same endpoint and the
Accept header to request these statistical representations?
GET /tasks?createdDate=01-01-2022&completedDate=30-01-2022 Accept: application/vnd.metric+meanTimeToCompleteTask+json GET /tasks?isOpen=true&priority=high` Accept: application/vnd.metric+count+json
Or should a separate endpoint be used?
Note: for these metric representations PUT/POST/PATCH/DELETE would not be allowed, they're a GET only operation.
What I like about the the content negotiation approach is that as a consumer of the API, you don't need to familiarise yourself with another API endpoint - your queries are going to match the query you would make if were calculating the values yourself.
Bounty Edit: I want to make it clear why I think using an Accept header against the same endpoint would be a good idea:
- Necessarily, the same set of query parameters can be used to define the list of data that determines the metric, as is used to fetch said of data itself.
- If you were to use two separate endpoints, they might well happen to have the same set of query parameters, but that is not a necessary coincidence. It's conceivable that they would fall out of sync.