API: Stats

DRAFT PROPOSAL: NOT IMPLEMENTED

Any list endpoint may need summary statistics. Every endpoint would return a different model for their own stats model. We don't expect much standardization on the models returned.

More structured reports that serve a specific purpose should be modelled into their own resources. However, the one example of a report we have at the moment still respects the structure of this resource definition. That's a good thing.

A resource that supports stats:

• is a list endpoint (e.g. /projects)
• NOT a single resource (e.g. not /projects/1)

The aggregate entity:

• can be accessed via the sub-route .../stats
  • GET request (e.g. GET /projects/stats)
  • or via a filter request (e.g. POST /projects/stats)
    • only the filter part of a standard API filter request body is supported
• returns a standard API response
• returns a single object API response
• can accept additional parameters not related to filtering via the options pattern