meta api

Meta API

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

Returns JSON describing a single release of a distribution. This method requires that the distribution name and version be known; these values can be retrieved from the following APIs:

• meta
• dist
• extension
• user
• tag

Mirror API Structure

The structure of this JSON file on mirror servers is similar to that defined by the PGXN Meta Spec, though with some variation. A few examples:

• pgTAP 0.25.0 META.json
• pair 0.1.2 META.json
• italian_fts 1.2.1 META.json

The contents constitute a single JSON object with the following keys ("P" column indicates keys which are always present):

P	Key	Type	Description
•	name	String	The name of the distribution.
•	version	SemVer	The semantic version of this release of the distribution.
•	abstract	String	A brief description of the distribution.
•	user	String	The nickname of the user who uploaded this release of the distribution.
•	sha1	String	The SHA1 hash for the download for this release of the distribution.
•	date	Date	The date the release was uploaded to PGXN.
•	release_status	String	The status of this release of the distribution. Maybe one of: stable, testing, unstable.
•	license	String, Array, Object	The license or licenses under which this release of the distribution is distributed. Details.
•	maintainer	String, Array	A string or array listing the maintainers of the distribution. Details.
•	provides	Object	Lists the extensions provided by this release of the distribution. Details.
	description	String	A longer description of the distribution.
	tags	Array	Lists one or more tags (keywords) for the distribution.
	prereqs	Object	Lists the names and minimum versions of prerequisite extensions for the configuration, building, testing, and running of the extensions in the distribution. Details.
	resources	Object	Lists online resources related to the distribution, such as source code repositories and bug tracking systems. Details.
	no_index	Object	Lists files and directories that should not be indexed. Details.

Refer to the PGXN Meta Spec for details on all of these values. This META.json file differs from that mandated to be included in the distribution files by in the following ways:

• Has the additional user, sha1, and date keys.
• Does not have the generated_by or meta-spec keys.
• Guaranteed to have the provides key.

API Server Structure

The structure of the JSON returned by the API server is a superset of that returned by a mirror. Some examples:

• pgTAP 0.25.0 META.json
• pair 0.1.2 META.json
• italian_fts 1.2.1 META.json

The API server offers the following additional keys ("P" column indicates keys which are always present):

P	Key	Type	Description
•	docs	Object	An object describing documentation files found in this release of the distribution. See below
•	special_files	Array	Lists the paths to special files in the distribution, such as Changes, README, INSTALL, License, and others.
•	releases	Object	Provides a complete history of all releases of the distribution, including those that were released after this release. See below.
•	provides	Object	In addition to the keys provided by all mirror servers, the API server adds one more: docpath (String; Optional): The path to the documentation file for the extension, sans file name suffix.

docs

For this object the keys are paths to the documentation files sans file name suffix. The values are objects containing the following keys ("P" column indicates keys which are always present):

P	Key	Type	Description
•	title	String	The title of the documentation.
	abstract	String	A brief description of the documentation. Provided when a documentation file corresponds to a provided extension name.

Example:

"docs": {
   "README": {
      "title": "pair 0.1.2"
   },
   "doc/pair": {
      "abstract": "A key/value pair data type",
      "title": "pair 0.1.2"
   }
}

releases

This object provides a complete history of all releases of the distribution, including those that were released after this release. 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"
      }
   ]
}

Perl Example

Assuming you have retrieved the JSON document from the index API and stored the data in the $table hash, you can fetch and parse the META.json for version 1.1.0 of the "pair" distribution like so:

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

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