New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
preaction opened this Issue May 22, 2017 · 5 comments

Comments

Projects
None yet
2 participants
@preaction
Member

preaction commented May 22, 2017

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?

@preaction preaction changed the title from Add flag to get only information for the latest release of a distribution to Add query parameters to get information for the latest release of a distribution Nov 10, 2017

@1nickt

This comment has been minimized.

Show comment
Hide comment
@1nickt

1nickt Nov 17, 2017

Contributor

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.

Contributor

1nickt commented Nov 17, 2017

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

This comment has been minimized.

Show comment
Hide comment
@preaction

preaction Nov 17, 2017

Member

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.

Member

preaction commented Nov 17, 2017

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

This comment has been minimized.

Show comment
Hide comment
@1nickt

1nickt Nov 20, 2017

Contributor

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?

Contributor

1nickt commented Nov 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@preaction

preaction Nov 20, 2017

Member

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 ;)

Member

preaction commented Nov 20, 2017

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

This comment has been minimized.

Show comment
Hide comment
@1nickt

1nickt Nov 20, 2017

Contributor

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

Contributor

1nickt commented Nov 20, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment