extension api

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

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:

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:

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