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

Tag API

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

Returns JSON describing all distribution releases associated with a tag. Tags are simple text strings optionally provided as metadata by distribution maintainers.

Mirror API Structure

The structure of this JSON file on mirror servers provides the tag name and list of distribution releases. A few examples:

The contents constitute a single JSON object with the following keys:

Key Type Description
tag String The tag itself.
releases Object A list of all releases of distributions associated with the tag.

releases

This object lists all releases of distributions associated with the tag. The keys are distribution names. The values are objects with release statuses for keys (stable, testing, or unstable) and arrays of release information for values. The keys provided by those objects are as follows:

Key Type Description
version SemVer The semantic version of the release.
date Date The date of the release of the distribution.

Example:

"releases": {
   "pg_french_datatypes": {
      "stable": [
         {"version": "0.1.1", "date": "2011-01-30T16:51:16Z"}
      ]
   },
   "pgmp": {
      "testing": [
         {"version": "1.0.0b3", "date": "2011-04-22T20:15:25Z"},
         {"version": "1.0.0b2", "date": "2011-04-21T22:44:48Z"}
      ]
   }
}

API Server Structure

The data provided by the API Server implementation of this method is identical to that provided by Mirror API with one addition. Some examples:

The following key will be added to the object describing a distribution:

Key Type Description
abstract String A brief description of the distribution.

Example:

"releases": {
   "pg_french_datatypes": {
      "abstract": "french-centric data type",
      "stable": [
         {"version": "0.1.1", "date": "2011-01-30T16:51:16Z"}
      ]
   },
   "pgmp": {
      "abstract": "PostgreSQL Multiple Precision Arithmetic extension",
      "testing": [
         {"version": "1.0.0b3", "date": "2011-04-22T20:15:25Z"},
         {"version": "1.0.0b2", "date": "2011-04-21T22:44:48Z"}
      ]
   }
}

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 "key value" tag like so:

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

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