dist api

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:

• countnulls.json
• pair.json
• pgmp.json

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};