Docs.rs API

[Kixiron]

Adds an api for shields.io to query docs.rs with.

Users can call /api/v1/badges?crate=<crate> for the latest version of a crate and /api/v1/badges?crate=<crate>&version=<version> for a specific version.
The api returns the crate name, release version, the url of the crate (e.g. https://docs.rs/crate/rcc/0.0.0) and the crate's build status, which can be one of the following:

• built fully built and available
• failed the build failed in some way
• queued the release is in the build queue
• yanked the release has been yanked
• not_library the release isn't a library (Not 100% sure about this one since Document a binary? #238 is a thing)

The api is versioned so that we have future-compatibility. I'm not entirely sure how to handle the old badge system, ideally we'd be able to remove it entirely and forward requests, but that's not possible until shields.io has a working thing, which isn't possible until we have a working thing

[pietroalbini]

I don't have the time to do a full review right now, but other than the commit I left I'm not sure this is the right API design. This seems more like a generic API for docs.rs rather than an API just for badges.

I think we could structure the API this way:

• /-/api/v1/crates/{name}: return information on all the versions

  {
    "name": "crate-name",
    "versions": [
      {
        "version": "1.0.0",
        "docs-url": "https://...",
        "build-status": "built"
      }
    ]
  }

• /-/api/v1/crates/{name}/versions/{version}: return information on a single version

  {
    "crate": "crate-name",
    "version": "1.0.0",
    "docs-url": "https://...",
    "build-status": "built"
  }

[pietroalbini]

We shouldn't add more reserved prefixes.

I propose all new top-level routes should be prefixed by -, for example:

/-/api/v1/badges

[Kixiron]

What does the - do, I'm not familiar with it

[pietroalbini]

It's just a name that can't be registered on crates.io.

[pietroalbini]

When doing tests on the API I'd match with serde_json::Value (generating the expected result with the json! macro), so we can guarantee the result will be the same regardless of bugs or changes in the serialization code.

[leos]

It would be useful to be able to get a list of the versions available of the docs of any given crate

• basically the equivalent of: https://docs.readthedocs.io/en/latest/api/v3.html#versions-listing

In general, the RTD api is probably a good starting point for what would be useful on docs.rs.

[Kixiron]

I think I've got a decent api design that should be plenty good for the foreseeable future

• /-/api/v1/crates/{crate_name}/versions See all released versions of a crate, paginated with the limit and offset parameters

{
    "total": 25, // Total number of releases for this crate
    "next": "https://docs.rs/-/api/v1/crates/{crate_name}/versions/?limit=10&offset=20",     // The next page of releases or `null`
    "previous": "https://docs.rs/-/api/v1/crates/{crate_name}/versions/?limit=10&offset=10", // The previous page of releases or `null`
    "latest": "https://docs.rs/-/api/v1/crates/{crate_name}/versions/{latest_version}",      // The latest release of the crate
    "releases": [
        {
            "version": "{release_version}",
            "url": "https://docs.rs/-/api/v1/crates/{crate_name}/versions/{release_version}",
            "status": "{build_status}", // One of "built", "queued" or "failed"
            "yanked": false
        }
    ]
}

• /-/api/v1/crates/{crate_name}/versions/{version} Information on one specific version of a crate

{
    "version": "{version}",
    "crate_name": "{crate_name}",
    "project_name": "{project_name}",
    "status": "{build_status}", // One of "built", "queued" or "failed"
    "yanked": false,
    "build_time": "2020-06-06T23:31:13+00:00", // RFC 3339 timestamp or `null` if the crate failed to build
    "urls": {
        "documentation": "https://docs.rs/{project_name}/{version}/{crate_name}", // Will be `null` if the crate failed to build
        "crate": "https://docs.rs/crate/{crate_name}/{version}",
        "builds_html": "https://docs.rs/crate/{crate_name}/{version}/builds",
        "builds": "https://docs.rs/crate/{crate_name}/{version}/builds.json",
        "source": "https://docs.rs/crate/{crate_name}/{version}/source" // Will be `null` if the crate failed to build
    },
    "dependencies": [
        "https://docs.rs/-/api/v1/crates/{dep_name}/versions/{dep_version}"
    ]
}

[teymour-aldridge]

Suggested change

	/// The json data of a crate release
	/// The JSON data of a crate release

[teymour-aldridge]

Suggested change

	/// The badge api, expects `?crate=<string>` and an optional `version=<string>`, if the version is not
	/// The badge API expects `?crate=<string>` and an optional `version=<string>` – if the version is not

[jyn514]

As per #170 (comment), I would prefer we fixed the latest bug rather than introducing a completely new API.