Designing REST api for returning count of multiple objects

[API Dev]

I have a question on how should I design my rest api(s) given that I need to return count of different objects in my application. There are multiple approaches that could be thought off

1. Defining a single api that generally accepts the object identifier in the request body (json) and returns back the count for each of the object identifiers in the response. The drawback is the api is too generic and possibly not restful since there is no resource. The url would look like GET /counts

2. Define individual api's for each of the resources for which count is needed. Assuming I need to return counts for the fields defined in the software, tables, processes, tasks, jobs etc I would define individual api's for each of these resources. It would look like GET /field/count or GET /table/count. A side effect of this would be there would be many web api's for each of the resources we need the count for. Is that bad?

Kindly share your thoughts on the above approaches and any new ways in which I could design such an API that adheres to the REST standards.

Thanks.

P.S - I have come across a couple of threads on this forum on a similar topic but my requirement seemed a bit different hence thought of spawning a new discussion

[Johan Vester]

As an API consumer, I would expect each count value to be represented either as a subresource to the countable resource (i.e. GET /tasks/count for a count of tasks), or as a field in a bigger aggregation of metadata related to the concerned resource (i.e. GET /tasks/metadata). By scoping related endpoints under the same parent resource (i.e. /tasks), the API becomes intuitive, and the purpose of an endpoint can (usually) be inferred from its path and HTTP method.

Additional thoughts:
1. If each individual count is only useful in combination with other counts (for a statistics dashboard, for example), you could possibly expose a single endpoint which aggregates and returns all counts at once.

2. If you have an existing endpoint for listing all resources (i.e. GET /tasks for listing all tasks), the count could be included in the response as metadata, either as HTTP headers or in the response body. Doing this will incur unnecessary load on the API, which might be negligible depending on your use case.

Regards

[API Dev]

Thanks for the reply. We do not have existing endpoints for any of the resources. For the current use case all the counts would be useful only in combination, so a single endpoint seems good as you suggest. 

Also assuming there would be no specific resource in the rest api endpoint, I was under the impression that such a design would not be restful as some of the links state here. Basically api's that accept generic payloads are not considered restful.

How do you visualize the REST api to look like? I mean the url. I assume the resource names would be generically passed as an array in the form of a json, right?

I appreciate your valuable inputs on this discussion. Thanks !

[Lukas Rosenstock]

Am 19.01.2017 um 14:11 schrieb API Dev <amit...@gmail.com>:

Thanks for the reply. We do not have existing endpoints for any of the resources. For the current use case all the counts would be useful only in combination, so a single endpoint seems good as you suggest. 

If that’s your use case I would also suggest using a single API endpoint like GET /counts, making the counts a top-level resource. If you want filtering it can be added in the query, e.g. GET /counts?types=jobs,tasks.

Also assuming there would be no specific resource in the rest api endpoint, I was under the impression that such a design would not be restful as some of the links state here. Basically api's that accept generic payloads are not considered restful.

I think it’s important to know that REST is a good design principle but it is not a purpose or goal in itself. For some use cases it is very difficult to design an API that is both good in terms of RESTful design but also good in terms of developer experience. Just be aware of the tradeoffs.

Lukas Rosenstock

https://cloudobjects.io/

[API Dev]

Thanks for your comments.

> If that’s your use case I would also suggest using a single API endpoint like GET /counts, making the counts a top-level resource. If you want filtering it can be added in the query, e.g. GET /counts?types=jobs,tasks.

Right a single endpoint would be good. Is there a specific reason you mention about accepting the individual resource names as a query string vs accepting them as part of the body in the form of a json? I understand the data is generally accepted in the body for a PUT request while for GET request it is generally done through query parameters. I was thinking from the point of view of being extensible - adding more details for filtering the GET request.

> I think it’s important to know that REST is a good design principle but it is not a purpose or goal in itself. For some use cases it is very difficult to design an API that is both good in terms of RESTful design but also good in terms of developer experience. Just be aware of the tradeoffs.

Ok. I will keep that in mind. Thanks again.

[Lukas Rosenstock]

> Right a single endpoint would be good. Is there a specific reason you mention about accepting the individual resource names as a query string vs accepting them as part of the body in the form of a json? I understand the data is generally accepted in the body for a PUT request while for GET request it is generally done through query parameters. I was thinking from the point of view of being extensible - adding more details for filtering the GET request.

While it’s not technically forbidden to use a request body in combination with GET it is an extremely rare practice and some HTTP clients and servers do not support it. You should never use GET with a body.

Discussion about this: http://stackoverflow.com/questions/978061/http-get-with-request-body

Lukas Rosenstock
https://cloudobjects.io/