> Aloha guardians of the API! > > I haven recently* reviewed a spec for neutron [1] proposing a distinct URI > for returning resource count on list operations. > This proposal is for selected neutron resources, but I believe the topic is > general enough to require a guideline for the API working group. Your > advice is therefore extremely valuable. > > In a nutshell the proposal is to retrieve resource count in the following > way: > GET /<prefix>/<resource_name>/count > > In my limited experience with RESTful APIs, I've never encountered one that > does counting in this way. This obviously does not mean it's a bad idea. > I think it's not great from a usability perspective to require two distinct > URIs to fetch the first page and then the total number of elements. I > reckon the first response page for a list operation might include also the > total count. For example: > > {'resources': [{meh}, {meh}, {meh_again}], > 'resource_count': 55 > <link_to_next_page>}
How about allowing the caller to specify what level of detail they require via the Accept header? ▶ GET /<prefix>/<resource_name> Accept: application/json; detail=concise ◀ HTTP/1.1 200 OK Content-Type: application/json {'resource_count': 55, <other_collection-level_properties>} ▶ GET /<prefix>/<resource_name> Accept: application/json ◀ HTTP/1.1 200 OK Content-Type: application/json {'resource_count': 55, <other_collection-level_properties>, 'resources': [{meh}, {meh}, {meh_again}], <link_to_next_page>} Same API, but the caller can choose not to receive the embedded resource representations if they're only interested in the collection-level properties such as the count (if the collection is indeed countable). Cheers, Eoghan > I am however completely open to consider other alternatives. > What is your opinion on this matter? > > Regards, > Salvatore > > > * it's been 10 days now > > [1] https://review.openstack.org/#/c/102199/ _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev