tag api

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:

• datatype.json
• integer.json
• key value.json

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:

• datatype.json
• integer.json
• key value.json

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('http://master.pgxn.org' . $uri);
my $dist = decode_json $res->{content};