API

Version 2 of the pub.dartlang.org JSON API is available from http://pub.dartlang.org/api. It's intended to be largely self-documenting; each page includes links to other related pages. Each resource is represented in one of two forms: a compact form used when the resource is embedded in another page, and a full form when requesting the resource directly.

General Concepts

Accept Header

The API is versioned using the Accept header. Clients should provide an Accept header of the form application/vnd.pub.${version}+json, where version is the most recent version of the API the client understands. Currently the latest version is v2, so clients should send Version: application/vnd.pub.v2+json.

If the API changes in incompatible ways in the future, pub.dartlang.org will continue to serve the old version to clients requesting it via the Accept header. If a client doesn't include an Accept header, it will receive the latest version of the API; this is very much not recommended, since the latest version may change in backwards-incompatible ways.

Links

The resources served by the API contain key/value pairs representing links to other resources. The key is of the form url or ${name}_url, and the value uses the RFC 6570 URI template format. When possible, clients should follow these links rather than hard-coding the entrypoint URLs.

Common Resources

Packages

The URL for a package is http://pub.dartlang.org/api/packages/{package}. A package looks like this:

{
  "url": "http://pub.dartlang.org/api/packages/yaml",
  "uploaders_url": "http://pub.dartlang.org/api/packages/yaml/uploaders",
  "version_url": "http://pub.dartlang.org/api/packages/yaml/versions/{version}",
  "name": "yaml",
  "latest": (package version),
  "uploaders": ["[email protected]", "[email protected]"],
  "versions": [(package versions)...],
  "created": "2013-02-05T17:01:24.685390",
  "downloads": 288
}

It has the following fields:

• url is the URL for this package.
• uploaders_url is the URL for manipulating the uploaders of this package.
• version_url is the URL template for versions of this package.
• name is this package's name.
• latest is the compact form of the latest version of this package. This refers to the version that would get installed when running pub install with no version constraints; it's the highest-numbered non-prerelease version of the package.
• uploaders is the list of users who are allowed to upload new versions of this package.
• created is the ISO 8601-format time the first version of this package was uploaded.
• downloads is the number of times any version of this package has been downloaded.

A compact package is missnig the uploaders, created, and downloads fields.

Package Versions

The URL for a package version is http://pub.dartlang.org/api/packages/{package}/versions/{version}. A package version looks like this:

{
  "url": "http://pub.dartlang.org/api/packages/yaml/versions/0.5.20",
  "package_url": "http://pub.dartlang.org/api/packages/yaml",
  "archive_url": "http://pub.dartlang.org/packages/yaml/versions/0.5.20.tar.gz",
  "version": "0.5.20",
  "pubspec": {
    "environment": {"sdk": ">=0.5.20"},
    "version": "0.5.20",
    "description": "A parser for YAML.",
    "author": "Dart Team <[email protected]>",
    "dev_dependencies": {"unittest": "any"},
    "homepage": "http://www.dartlang.org",
    "name": "yaml"
  },
  "downloads": 2,
  "created": "2013-06-17T22:09:37.231000",
  "libraries": ["yaml.dart"],
  "uploader": "[email protected]"
}

It has the following fields:

• url is the URL for this package version.
• package_url is the URL for the package that this package version belongs to.
• archive_url is the URL for the tar+gzip archive containing the contents of this package version.
• version is the this package version's semantic version.
• pubspec is a JSON encoding of this package version's pubspec.
• downloads is the number of times the archive has been downloaded.
• created is the ISO 8601-format time this package version was uploaded.
• libraries is a list of user-visible libraries in the package version (that is, Dart files in lib but not lib/src).
• uploader is the user who uploaded this package in particular.

A compact package version is missing the downloads, created, libraries, and uploader fields.

Other Resources

Root

The API root is located at http://pub.dartlang.org/api. It contains links to all top-level resources.

{
  "packages_url": "http://pub.dartlang.org/api/packages{/package}"
}

Currently there's only one field:

• packages_url is the URL template for the package list or, with a parameter, for a specific package.

Package List

The package list is located at http://pub.dartlang.org/api/packages. It's the first page of a paginated list of all packages in the repository. It looks like this:

{
  "next_url": "http://pub.dartlang.org/api/packages?page=2",
  "prev_url": null,
  "pages": 7,
  "packages": [(packages)...]
}

It has the following fields:

• next_url is the URL of the next page of packages, or null if this is the last page. Clients shouldn't assume the format of this URL will remain consistent. Changing it will not be considered a breaking change.
• prev_url is the URL of the previous page of packages, or null if this is the first page. Clients shouldn't assume the format of this URL will remain consistent. Changing it will not be considered a breaking change.
• pages is the total number of pages of packages.
• packages is the list of compact packages in this page.

Package Uploaders

Package uploaders are a write-only resource located at http://pub.dartlang.org/api/packages/{package}/uploaders{/uploader}.

An uploader can be added to a package by sending an application/x-www-form-urlencoded POST request to http://pub.dartlang.org/api/packages/{package}/uploaders. The body contain an email field with the email address of the uploader to add.

An uploader can be removed from a package by sending a DELETE request to http://pub.dartlang.org/api/packages/{package}/uploaders/{uploader}. The uploader parameter should be the email of the uploader to remove.