Skip to content
David E. Wheeler edited this page Mar 23, 2017 · 8 revisions

Distribution API

  • Name: dist
  • Returns: application/json
  • URI Template Variables: {dist}
  • Availability: Mirror Server, API Server

Returns JSON describing all releases of a distribution. This method requires that the distribution name be known; if no distribution exists with the specified name, a 404 response will be returned.

Mirror API Structure

The structure of this JSON file on mirror servers is quite simple. A few examples:

The contents constitute a single JSON object with the following keys:

Key Type Description
name String The name of the distribution.
releases Object Lists all releases of the distribution.

releases

This object provides a complete history of all releases of the distribution. They keys are release statuses:

  • stable
  • unstable
  • testing

There will always be at least one status. The values for each status are arrays of objects. Each object describes a release, and they are listed in the array in reverse chronological order. They supported keys are:

Key Type Description
date Date The date of the release.
version SemVer The semantic version of the release.

Example:

"releases": {
   "stable": [
      {
         "date": "2011-04-20T23:47:22Z",
         "version": "0.1.2"
      },
      {
         "date": "2010-10-29T22:44:42Z",
         "version": "0.1.1"
      },
   ],
   "testing": [
      {
         "date": "2010-10-19T03:59:54Z",
         "version": "0.1.0"
      }
   ]
}

API Server Structure

The structure of the JSON returned by the distribution API is identical to that returned for the latest version of the distribution by the meta API. This is to simplify the display of all data for a distribution. This is how PGXN::Site shows all the data for a distribution with a single API request (example). Please refer to the meta API documentation for the details.

Perl Example

Assuming you have retrieved the JSON document from the index API and stored the data in the $table hash, you can fetch the JSON describing the "pair" distribution like so:

use URI::Template;
use HTTP::Tiny;
use JSON;
my $tmpl = URI::Template->new($table->{dist});
my $uri = $tmpl->process({ dist => 'pair' });

my $req  = HTTP::Tiny->new;
my $res  = $req->get('https://master.pgxn.org' . $uri);
my $dist = decode_json $res->{content};
Clone this wiki locally