Open Stack

> 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/