Add query parameters to get information for the latest release of a distribution

[preaction]

The release API gets information rolled-up by distribution and version into a simple set of pass/fail/na/unknown statistics. By default, this gives information for every single release of every single distribution, which is good for sites like http://metacpan.org (which this API was initially designed for) but bad for other kinds of consumption.

So, to all the release API endpoints (/v3/release, /v3/release/dist/:dist, /v3/release/author/:author) we should add two new query parameters: maturity and per_dist.

For maturity, the value can be either stable, which limits the results returned to only the stable releases of the distribution, or dev, which limits the results returned to only development releases of the distribution. The default behavior is to get all releases of a distribution (maturity=any).

For per_dist, the value is an integer that will limit how many versions of each distribution will be returned. The default behavior is to get all versions of a distribution.

The combined result of these two parameters means that setting ?per_dist=1&maturity=stable will get you a report of only the latest stable release of the distribution(s).

For example, given a distribution Foo released by FIZZBUZZ, with versions 1.0, 1.000_001 (a dev version), and 1.1, and a distribution Bar released by FIZZBUZZ with versions 20170101, and 20170205-TRIAL:

• /v3/release/dist/Foo?maturity=stable will return the information for releases 1.0 and 1.1.
• /v3/release/dist/Foo?maturity=stable&per_dist=1 will return the information for release 1.1.
• /v3/release/dist/Foo?maturity=dev will return the information for release 1.000_001.
• /v3/release/author/FIZZBUZZ?maturity=stable&per_dist=1 will return information for Foo@1.1 and Bar@20170101
• /v3/release/author/FIZZBUZZ?per_dist=1 will return information for Foo@1.1 and Bar@20170205-TRIAL
• /v3/release?maturity=dev&per_dist=1 will return information for Foo@1.000_001 and Bar@20170205-TRIAL

Questions:

• Is the name per_dist okay? Is there a better name? Just per? each? results_per_dist?
  • It can't be limit because that should limit the total number of responses, not the responses for each distribution.
• Should /v3/release/dist/Foo allow per_dist? Or should it just be named limit for this endpoint?

[1nickt]

Hi, I'm wondering about "It can't be limit because that should limit the total number of responses, not the responses for each distribution".

Maybe I'm missing something*, but isn't "the total number of responses" the same as the responses for a dist, if you have requested /v3/release/dist/{dist} ? So adding a param limit would apply to either a singles dist's releases, or to all dists' releases if that's what you requested.

*(i.e., a way to request more than one but less than all dists)

Unless you mean that want to be able to request all dists but only up to a max limit per dist, and also be able to limit the total number of responses ... then it should be a separate param, I suggest limit_per_dist.

[preaction]

The /v3/release API returns all dists and all versions, and the /v3/release/author/{author} returns all of an author's dists and versions. It would be nice if I could then say "only get me the latest version of every dist": Building an author dashboard likely only wants that information, not every single dist.

Especially when it comes to /v3/release: This API is slow. Limiting the amount of data we return could make this API faster.

[1nickt]

Hi @preaction do you want support for maturity value any in the API or are you just saying that would be the effective default? I can't see a good reason to support passing it as a value if it's just going to be discarded, but maybe there is one?

[preaction]

Nah, I think you're right: It's the default, so there's no need to explicitly do it. Each constraint is layered on the previous. If they don't want to constrain, they don't need to declare "I want all things". They can declare it explicitly by not declaring it ;)

[1nickt]

Hey @preaction, maturity is done. I have family in town so probably won't get to limit_per_dist until the weekend at least.