Announcing the Package & Versions API

Packagecloud Ops

Apr 26, 2015 · 3 min read

announcements

TL;DR

You can finally list, filter, and view packages via the packagecloud.io API!

Feel free to jump right into the docs:

Or, continue reading for details and examples.

A note about Pagination

All of the API’s in this post (excluding the Package API) return a set of items, which can be paginated. Check out the Link: header in the HTTP response to view pagination information, like the next and last page.

Packages API

We’ll start with the Packages API. There are actually two flavors of this API:

Packages “All” API

This API is a package-for-package listing of all the packages in your repository, similar to the repository pages on the website.

You can access it via: /api/v1/repos/:user/:repo/packages.json

And it looks like:

  [
    {
      "name": "packagecloud-test",
      "distro_version": "el/6",
      "created_at": "2014-07-16T16:22:05.000Z",
      "version": "1.1",
      "release": "1",
      "epoch": 0,
      "private": false,
      "type": "rpm",
      "uploader_name": "joe",
      "repository_html_url": "/computology/packagecloud-test-packages",
      "package_url": "/api/v1/repos/computology/packagecloud-test-packages/package/rpm/el/6/packagecloud-test/src/1.1/1.json",
      "package_html_url": "/computology/packagecloud-test-packages/packages/el/6/packagecloud-test-1.1-1.src.rpm"
    },
    {...}
  ]

Package Filtering API

Instead of a package-for-package listing, this API rolls up package versions by name and returns links to more versions of the package. So, if you have 1 package with 20 versions, this API will return one object, with a link to a collection of the 20 versions.

This API also supports a robust criteria for filtering packages by name, architecture, distribution, or specific distribution version.

At it’s most basic, you can filter by package type:

/api/v1/repos/:user/:repo/packages/gem.json

You can also filter by distribution:

/api/v1/repos/:user/:repo/packages/deb/ubuntu.json

Or, by distribution version:

/api/v1/repos/:user/:repo/packages/deb/ubuntu/trusty.json

Even by architecture:

/api/v1/repos/:user/:repo/packages/deb/ubuntu/trusty/amd64.json

Wildcards also work as you expect:

/api/v1/repos/:user/:repo/packages/deb/ubuntu/*/amd64.json

/api/v1/repos/:user/:repo/packages/rpm/*/*/x86_64.json

This results is is JSON collection of PackageVersions, that looks like:

[
  {
    "name": "packagecloud-test",
    "versions_count": 1,
    "versions_url": "/api/v1/repos/computology/packagecloud-test-packages/package/deb/ubuntu/precise/packagecloud-test/amd64/versions.json",
    "repository_url": "/api/v1/repos/computology/packagecloud-test-packages",
    "repository_html_url": "/computology/packagecloud-test-packages"
  },
  {...}
]

Versions API

You’ll notice that the Packages Filtering API response contains a versions_url field for every package. It looks like:

/api/v1/repos/:user/:repo/package/:type/:dist/:version/:package/:arch/versions.json

For gems, it’s simply:

/api/v1/repos/:user/:repo/package/gem/:package/versions.json

This API url returns all of the versions for that package, distribution, and distribution version. For instance:

/api/v1/repos/computology/packagecloud-test-packages/package/deb/ubuntu/precise/packagecloud-test/amd64/versions.json

This URL is requesting all of the package versions associated with the packagecloud-test package of type deb on ubuntu/precise for the computology/packagecloud-test-packages repository. The response looks like:

  [
    {
      "name": "packagecloud-test",
      "distro_version": "ubuntu/precise",
      "created_at": "2014-07-17T18:27:33.000Z",
      "version": "1.1",
      "release": "2",
      "epoch": 0,
      "private": false,
      "type": "deb",
      "uploader_name": "joe",
      "repository_html_url": "/computology/packagecloud-test-packages",
      "package_url": "/api/v1/repos/computology/packagecloud-test-packages/package/deb/ubuntu/precise/packagecloud-test/amd64/1.1-2.json",
      "package_html_url": "/computology/packagecloud-test-packages/packages/ubuntu/precise/packagecloud-test_1.1-2_amd64.deb"
    },
    {...}
  ]

Package API

Similarly, following the package_url link returns the PackageDetails response for a given package.

For example:

/api/v1/repos/computology/packagecloud-test-packages/package/deb/ubuntu/precise/packagecloud-test/amd64/1.1-2.json

  {
    "name": "packagecloud-test",
    "distro_version": "ubuntu/precise",
    "architecture": "amd64",
    "repository": "packagecloud-test-packages",
    "size": "2830",
    "summary": null,
    "filename": "packagecloud-test_1.1-2_amd64.deb",
    "description": "packagecloud-test a hello world program from the packagecloud crew",
    "md5sum": "b709d6a5b2e6883ee97803e5fd1b204e",
    "sha1sum": "ba4500d3b385aced8c8ed3c48981eba2dd2005b4",
    "sha256sum": "8ed8bb73915088d422c26ce3e92c6477b3afdfcd7377713880db8ba68a697289",
    "sha512sum": "afcde64a1bfc5fdce1fff00002a2007a7f05eef51e45eb223885b89e2deb45cefd51dd596d79dea1daf020312afb14967eaef2d1a4c45f7da28ec045bfc2efc6",
    "private": false,
    "uploader_name": "joe",
    "created_at": "2014-07-17T18:27:33.000Z",
    "licenses": [],
    "version": "1.1",
    "release": "2",
    "epoch": 0,
    "repository_url": "/api/v1/repos/joe/packagecloud-test-packages",
    "versions_url": "/api/v1/repos/computology/packagecloud-test-packages/package/deb/ubuntu/precise/packagecloud-test/amd64/versions.json",
    "package_html_url": "/computology/packagecloud-test-packages/packages/ubuntu/precise/packagecloud-test_1.1-2_amd64.deb",
    "self_url": "/api/v1/repos/computology/packagecloud-test-packages/package/deb/ubuntu/precise/packagecloud-test/amd64/1.1-2.json"
  }

Conclusion

Expect these changes to roll out to the packagecloud command line tool in the following weeks. We’re excited to see what kind of integrations this will enable for our users!