Add an HTTP API reference, if stable

[hcpl]

For now, there is this repo where you can grep up to date API in form of router paths and params.get (or query.get or maybe something else I haven't seen) which access keyword parameters, but this is not acceptable for everyday use.

Since there can be use cases where you need to retrieve data from crates.io, consider adding a reference page somewhere for an easy access.

[hcpl]

I'm trying to do it. WIP of the reference here: https://github.com/hcpl/crates.io-http-api-reference.

Some questions popped up:

• What does "following the crate" exactly mean? Just getting notifications for any changes of the crate or only version updates?
• Why does /versions return an empty list? What does it stand for?
• What are "category slugs"? This page doesn't explain much. I get the feeling that they are something like PyPI classifiers/categories, but I'm not sure.

[carols10cents]

Related: #731

What does "following the crate" exactly mean? Just getting notifications for any changes of the crate or only version updates?

I'm not sure what you mean by "any changes of the crate or only version updates"; what changes are on crates.io that aren't version updates right now?

The best way to see what following a crate means, I think, is to follow some crates and then go to your dashboard at https://crates.io/dashboard. The "Latest updates" section is for the crates you're following.

Why does /versions return an empty list? What does it stand for?

I actually have no idea; I left a note in the code to remind me to investigate the history of it someday :) Let me know if you figure it out!

What are "category slugs"? This page doesn't explain much. I get the feeling that they are something like PyPI classifiers/categories, but I'm not sure.

Yes, they are exactly like PyPI classifiers/categories, and I modeled /category_slugs after https://pypi.python.org/pypi?%3Aaction=list_classifiers specifically. That page contains the tokens that crate authors specify in their Cargo.toml in order to put their crates in categories. There's a little bit of documentation here and some history on the implementation of the feature here.

Please let me know if you have any other questions! This will be great to have, thank you!!

[hcpl]

Related: #731

Thank you for linking, didn't know that. Should have looked at A-docs issues first!

I'm not sure what you mean by "any changes of the crate or only version updates"; what changes are on crates.io that aren't version updates right now?

Updates in Web UI, best crates per period, recent dramatic changes of downloads (i.e. being trending and profitable to check out), etc. Granted, version update is one of the important reasons to be notified, but crates are not everything there.

The best way to see what following a crate means, I think, is to follow some crates and then go to your dashboard at https://crates.io/dashboard. The "Latest updates" section is for the crates you're following.

Then I should make a note to finish some libraries (at last!) so that I had a reason to register and publish something! :D
Also now, as I understood, following-related API is logged in-only (which makes sense).

I actually have no idea; I left a note in the code to remind me to investigate the history of it someday :) Let me know if you figure it out!

Well, the function krate::versions you linked works just fine under /crates/:crate_id/versions route. The route in question here is /versions with version::index attached.

Briefly looking at it I found an ids[] URL query parameter and its value is used to filter from a certain versions SQL table by id column: https://github.com/rust-lang/crates.io/blob/master/src/version.rs#L300-L312. I tried to experiment a bit, but all of these

$ curl 'https://crates.io/api/v1/versions?ids%5B%5D=0.1.0'
$ curl 'https://crates.io/api/v1/versions?ids%5B%5D=libc'
$ curl 'https://crates.io/api/v1/versions?ids%5B%5D=1&ids=%5B%5D=1.0&ids=%5B%5D=1.0.0'

returned just {"versions":[]}, which makes me suspect that either versions table is probably empty (since crates table should be a much lesser suspect) or something else, since I can't truly say what is the purpose of the versions table, only speculate.

So in the end, my assumption is that /version route and its children are to be abandoned or refactored now.

Yes, they are exactly like PyPI classifiers/categories, and I modeled /category_slugs after https://pypi.python.org/pypi?%3Aaction=list_classifiers specifically. That page contains the tokens that crate authors specify in their Cargo.toml in order to put their crates in categories. There's a little bit of documentation here and some history on the implementation of the feature here.

This means that /category_slugs are just text representation of categories for an easy view? Or something more like a TODO list which has been made public as an early preview? That said, the categories themselves are easy to understand, but the slugs feel a bit excessive.

Thank you for your answer too!

[iinuwa]

Would an OpenAPI spec be helpful for this? I've started one, and I think I have defined most of the endpoints that are relevant to external registry users. https://gist.github.com/iinuwa/20169f7609d86f5b630c5a4b1c7269d1

If this works, maybe this could be hosted at /api/v1/api-docs?