Skip to content
David E. Wheeler edited this page Aug 3, 2020 · 10 revisions

User API

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

Returns JSON describing all distribution releases made by a user. This method requires that the user's nickname be known; if no user exists with the specified nickname, a 404 response will be returned.

Mirror API Structure

The structure of this JSON file on mirror servers provides biographical and contact information for the user, as well as a list of distributions, if any. A few examples:

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

P Key Type Description
nickname String The user's nickname, or username.
name String The user's full name.
email String The user's full email address.
uri String The URI for the user's home page.
twitter String The user's Twitter username.
releases Object A list of all releases of distributions by the user.

releases

This object lists all releases of distributions made by the user. 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": {
   "italian_fts": {
      "stable": [
         {"version": "1.2.1", "date": "2011-04-25T03:40:23Z"},
         {"version": "1.2.0", "date": "2011-04-23T21:26:08Z"}
      ]
   },
   "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": {
   "italian_fts": {
      "abstract": "Italian full-text search dictionary",
      "stable": [
         {"version": "1.2.1", "date": "2011-04-25T03:40:23Z"},
         {"version": "1.2.0", "date": "2011-04-23T21:26:08Z"}
      ]
   },
   "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 user "theory" like so:

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

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