Some time ago there was a blog post about tracking FTP uploads using the FTP-Master changelogs API: Tracking your FTP uploads using the FTP-Master changelogs API.

I found it very useful because I was also tracking my uploads manually, and I was missing information about this API.

Example request:

xh "https://api.ftp-master.debian.org/changelogs?search_term=anton+gladky"

Returns a JSON array with all changelog entries matching the given search term:

[
  {
    "date": "Tue, 04 Jan 2011 21:04:28 +0100",
    "source": "admesh",
    "version": "0.95-8",
    "changedby": "Anton Gladky <gladky.anton@gmail.com>",
    "changelog": "admesh (0.95-8) unstable; urgency=low\n\n  * Rewritten debian/rules hopefully closes: #436373\n  * Applied patch from Bilal Akhtar <bilalakhtar@ubuntu.com>,\n    added fclose at the end of stl_print_neighbors function (closes: #597159)\n  * New maintainer (closes: #576168)\n  * Switch to dpkg-source 3.0 (quilt) format\n  * Updating and cleaning debian/rules, debian/copyright and debian/control\n"
  },
  {
    "date": "Sat, 08 Jan 2011 17:16:48 +0100",
    "source": "admesh",
    "version": "0.95-9",
    "changedby": "Anton Gladky <gladky.anton@gmail.com>",
    "changelog": "admesh (0.95-9) unstable; urgency=low\n\n  * Removed debian-changes-0.95-8 patch\n"
  },
]

Then I started using it. Calling the endpoint for my uploads returns almost 1MB of JSON data, dating back to 2011. This is not very convenient and wastes resources, because the Debian server transmits data that you usually only need once (and then cache).

I started to look deeper into the API and found that it returns a plain list of all uploads matching the search term. There is no way to filter the data.

So I decided to propose an update to this API to add more features and make it more convenient to use.

Unfortunately, it was not possible to update the existing API in a backward-compatible way. So a new version 2 of the API was created, and a versioned endpoint /v2/changelogs was added instead of the existing /changelogs.

v2 of the changelogs FTP-Master API Link to heading

The dakweb component of DAK is responsible for providing the web API for the FTP-Master archive. It is based on the Bottle Python web framework and uses the SQLAlchemy ORM to access the database.

The documentation and the list of changes for v2 of the changelogs FTP-Master API can be found here: DAK changelogs API v2

It supports the following new features:

  • search_term (existing parameter): full text search in the changelog entries
  • since (optional): ISO date/datetime (e.g. 2024-01-01 or 2024-01-01T12:00:00)
  • till (optional): ISO date/datetime upper bound (inclusive)
  • source (optional): exact source package name to restrict
  • since_id (optional): return only rows with id > since_id (id-based polling)
  • limit (optional): default 50, max 500
  • offset (optional): default 0

Most of these features are self-explanatory and add filtering and pagination.

Using these filters, it is pretty easy to implement resource-efficient polling to track your uploads.

By default, 50 results are returned. You can increase limit up to 500 results per request. If you use the since_id parameter, you can implement efficient polling to get only new uploads since your last request.

Here is an example request:

xh "https://api.ftp-master.debian.org/v2/changelogs?search_term=anton+gladky"

Returns:

{
	"count": 50,
	"limit": 50,
	"offset": 0,
	"has_more": true,
	"results": [
		{
			"id": 1393025,
			"date": "Tue, 04 Jan 2011 21:04:28 +0100",
			"source": "admesh",
			"version": "0.95-8",
			"changedby": "Anton Gladky <gladky.anton@gmail.com>",
			"changelog": "admesh (0.95-8) unstable; urgency=low\n\n  * Rewritten debian/rules hopefully closes: #436373\n  * Applied patch from Bilal Akhtar <bilalakhtar@ubuntu.com>,\n    added fclose at the end of stl_print_neighbors function (closes: #597159)\n  * New maintainer (closes: #576168)\n  * Switch to dpkg-source 3.0 (quilt) format\n  * Updating and cleaning debian/rules, debian/copyright and debian/control\n"
		}
	]
}

The real content is in the results array. Each entry has a unique id field. Additional metadata like count, limit, offset, and has_more is provided to help with pagination. This is the reason why the new version of the API was created and why it is not backward-compatible.

The original unversioned API endpoint /changelogs will remain functional for some time for backward compatibility, but it is recommended to switch to the new v2 endpoint.

This legacy endpoint returns a warning header:

warning: 299 dakweb "/changelogs is legacy; prefer /v2/changelogs (adds pagination & filters)"

and an x-preferred-endpoint header:

x-preferred-endpoint: /v2/changelogs

Sometime in 2026 the original unversioned endpoint will be deprecated and switched off.

I would like to thank Sergio Cipriano for implementing these changes originally, and Ganneff for reviewing and merging the changes.

Please use v2 of the changelogs FTP-Master API for tracking your uploads. It is a more convenient and resource-efficient way to do this.