meta api

Meta API

• Name: meta
• Params: None.
• Returns: application/json
• URI Template Variables: {dist}, {version}

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:

• name (String; Required): The name of the distribution.
• version (SemVer; Required): The semantic version of this release of the distribution.
• abstract (String; Required): A brief description of the distribution.
• user (String; Required): The nickname of the user who uploaded this release of the distribution.
• sha1 (String; Required): The SHA1 hash for the download for this release of the distribution.
• date (Date; Required): The date the release was uploaded to PGXN.
• release_status (String; Required): The status of this release of the distribution. Maybe one of:
  • stable
  • unstable
  • testing
• license (String, Array, or Object; Required): The license or licenses under which this release of the distribution is distributed. Details.
• maintainer (String, Array; Required): A string or array listing the maintainers of the distribution. Details.
• provides (Object; Required): Lists the extensions provided by this release of the distribution. The object keys are the names of of the provided extensions. The values are objects containing the following keys:
  • version (SemVer; Required): The semantic version of for the extension.
  • abstract (String; Required): A brief description of the provided extension.
  • file (String; Optional): The path to the file in the distribution that defines the extension.
  • docfile (String; Optional): The path to the file in the distribution containing documentation of the extension.
• description (String; Optional): A longer description of the distribution.
• tags (Array; Optional): Lists one or more tags (keywords) for the distribution.
• prereqs (Object; Optional): 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; Optional): Lists online resources related to the distribution, such as source code repositories and bug tracking systems. Details.
• no_index (Object; Optional): Lists files and directories that should not be indexed. Details

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:

• docs (Object; Required): An object describing documentation files found in this release of the distribution. They keys are paths to the documentation files sans file name suffix. The values are objects containing the following keys:
  • title (String; Required): The title of the documentation.
  • abstract (String; Optional): A brief description of the documentation. Provided when a documentation file corresponds to a provided extension name.
• special_files (Array; Required): Lists the paths to special files in the distribution, such as Changes, README, INSTALL, License, and others.
• releases (Object; Required): 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:
  • date (Date, Required): The date of the release.
  • version (SemVer, Required): The semantic version of the release.
• provides (Object; Required): 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.

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($uri);
my $meta = decode_json $res->{content};