extension api

Extension API

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

Returns JSON describing all distribution releases providing an extension. This method requires that the extension name be known; if no extension 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
extension	String	The name of the extension.
latest	String	The release status of the most recent distribution providing the extension.
stable	Object	Basic information on the latest stable release of a distribution providing the extension.
versions	Object	Distribution information for all versions of the extension.

stable

This object describes the latest stable distribution providing the extension. The expectation is that an installation client would request this JSON file and by default read the stable object in order to determine what distribution to download and install. The stable object contains the following keys:

Key	Type	Description
dist	String	The name of the distribution.
version	SemVer	The semantic version of the release.
sha1	String	The SHA1 hash for the distribution [[download

Example:

"stable": {
   "dist": "pair",
   "version": "0.1.2",
   "sha1": "9988d7adb056b11f8576db44cca30f88a08bd652"
},

versions

This object provides distribution information for every release of the extension. The keys are versions. The values are arrays containing objects describing each distribution release providing the extension. Yes, this implies that a single version of an extension may be provided by more than one distribution or by more than one release of a single distribution. The distributions are listed in reverse chronological order and each contains the following keys:

Key	Type	Description
dist	String	The name of the distribution.
version	SemVer	The semantic version of the release.

Example:

"versions": {
   "0.1.2": [
      { "dist": "pair", "version": "0.1.2" }
   ],
   "0.1.1": [
      { "dist": "pair", "version": "0.1.1" }
   ],
   "0.1.0": [
      { "dist": "pair", "version": "0.1.0" }
   ]
}

API Server Structure

The data provided by this API by the API server is a superset of that provided by the Mirror API. Some examples:

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

The difference are as follows:

stable

The stable object may have the following additional keys:

Key	Type	Description
abstract	String	A brief description of the extension.
docpath	SemVer	A path to the documentation file for the extension, sans the file name suffix.

Example:

"stable": {
   "abstract": "A key/value pair data type",
   "dist": "pair",
   "docpath": "doc/pair",
   "sha1": "9988d7adb056b11f8576db44cca30f88a08bd652",
   "version": "0.1.2"
}

versions

The objects describing each distribution providing the extension may have the following additional key:

Key	Type	Description
date	Date	The date of the release of the distribution.

Example:

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

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" extension like so:

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

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