Add multiple nums[] parameters support for GET /api/v1/crates/:name/versions

[eth3lbert]

This allows us to return specified versions by filtering with the ids[] parameter.

[eth3lbert]

We could also consider allowing ids[] to accept id or semver string (num).

[LawnGnome]

The functionality LGTM. 👍

We could also consider allowing ids[] to accept id or semver string (num).

I think I'd prefer to keep those separate — while it's theoretically possible to distinguish integer IDs from semvers, it feels to me like it would be less surprising for users and future us if we didn't try to infer extra meaning from the provided values.

Which, given that, I'm not sure if ids[] is the best name for the parameter, since ID feels like it more refers to versions.id than versions.num. Naming is hard, so I don't know what's better, but maybe num[] or versions[] might be clearer?

[eth3lbert]

I think I'd prefer to keep those separate — while it's theoretically possible to distinguish integer IDs from semvers, it feels to me like it would be less surprising for users and future us if we didn't try to infer extra meaning from the provided values.

fair enough!

Which, given that, I'm not sure if ids[] is the best name for the parameter, since ID feels like it more refers to versions.id than versions.num. Naming is hard, so I don't know what's better, but maybe num[] or versions[] might be clearer?

Given that we already responded with the field name num, I think num[] would be more straightforward. What do you think?

@Turbo87 Any thoughts?

[Turbo87]

it took me a while to figure this out, but it looks like the original reason for the ids[] design was https://github.com/emberjs/data/blob/v4.12.8/packages/adapter/src/rest.ts#L709, which explicitly hardcodes ids[] in Ember Data.

the JSON:API spec (https://jsonapi.org/recommendations/#filtering) OTOH seems to recommend something like GET /crates?filter[id]=foo,bar. we are not using most of JSON:API, but we've used it as inspiration and guidance already in the past too. since we already started with ids[] we should probably continue with that pattern though. at least for this generation of our API...

I agree with Adam that ids[] should refer to whatever we put into the id field of the corresponding API response. If we implement support for filtering by multiple num values then nums[] would probably be most consistent with what we currently have (matches the field name and uses pluralization). Admittedly, I'm not a huge fan of it, but in terms of consistency it wins.

[eth3lbert]

Rebased and feedback addressed!

[LawnGnome]

With that change, no concerns here. 👍