Home

The PGXN API

This GitHub repository contains the source code for the PGXN API. If you're interested in the details of how it works, check it out. This wiki, however, documents the REST API provided by PGXN mirrors and the PGXN API, which is itself a superset of the mirror API.

Definitions

Mirror: A PGXN mirror server. There may be any number of mirrors, each one providing HTTP access to the network contents, which are rsynced from the master mirror. Each mirror provides a lightweight REST API, which is documented in this wiki.

Master Mirror: The root mirror of the network, its contents are managed by an instance of PGXN Manager. Some details on how PGXN Manager works have been written up in this blog post. For the purposes of this documentation, it will be assumed that all mirror servers provide the same API. The master mirror therefore will not be mentioned again.

API Server: As PGXN mirror that provides a superset of the mirror API, and is powerd by PGXN::API, the code managed in this GitHub repository. This wiki documents the API it provides.

PGXN Site: A simple Web server that displays the contents of the a PGXN network by accesing an API Server and presenting them in a web browser. The canonical PGXN site is pgxn.org.

Index: The root index.json file on mirror and PGXN API servers. This document contains a JSON object listing all of the APIs available on the server.

PGXN Client: Software that connects to and communicates with a PGXN mirror or API Server. The canonical example is WWW::PGXN, a Perl module providing transparent access to that API.

Entry Point

The entry point for all PGXN mirrors and API Servers is the index.json document, or "Index," at the root of the mirror server or API URL. Examples:

• PGXN Master Mirror
• PGXN API Server

Structure

The contents of the Index is a JSON object identifying all available APIs. An example from a mirror server:

{
   "download":  "/dist/{dist}/{version}/{dist}-{version}.pgz",
   "readme":    "/dist/{dist}/{version}/README.txt",
   "meta":      "/dist/{dist}/{version}/META.json",
   "dist":      "/dist/{dist}.json",
   "extension": "/extension/{extension}.json",
   "user":      "/user/{user}.json",
   "tag":       "/tag/{tag}.json",
   "stats":     "/stats/{stats}.json",
   "mirrors":   "/meta/mirrors.json",
   "spec":      "/meta/spec.{format}"
}

PGXN API servers provide a superset of the mirror APIs; An example:

{
   "dist": "/dist/{dist}.json",
   "download": "/dist/{dist}/{version}/{dist}-{version}.pgz",
   "extension": "/extension/{extension}.json",
   "htmldoc": "/dist/{dist}/{version}/{+docpath}.html",
   "meta": "/dist/{dist}/{version}/META.json",
   "mirrors": "/meta/mirrors.json",
   "readme": "/dist/{dist}/{version}/README.txt",
   "search": "/search/{in}/",
   "source": "/src/{dist}/{dist}-{version}/",
   "spec": "/meta/spec.{format}",
   "stats": "/stats/{stats}.json",
   "tag": "/tag/{tag}.json",
   "user": "/user/{user}.json",
   "userlist": "/users/{char}.json"
}

The object keys name available REST APIs. The values are URI Templates, which must be evaluated to determine the URIs to make calls to the APIs. The ability to execute URI templates is crucial to the use of the PGXN API. Here are some available libraries (source):

• Erlang
• Haskell
• Java Java
• Perl
• PHP
• Python
• Ruby
• Ruby

Variables

There are two types of variables currently used in PGXN URI templates:

Simple Expansion: {var}:

A simple expansion. All characters not in the unreserved set of URI characters will be URI-encoded before expansion.

Reserved Expansion: {+var}:

Exactly like simple expansion, except that all characters not in the set of unreserved or reserved characters will be encoded.

Effectively, this means that a value such as foo/bar will be encoded by simple expansion as foo%2Fbar, while reserved expansions will be expanded as foo/bar. At of this writing, the only reserved expansion variable in use is {+docpath} in the htmldoc template offered by the API server. All other templates use simple expansion variables.

Variable Reference

A complete list of all URI Templates used in Mirror and API Server Index document URI Templates.

• {dist}: The name of a PGXN distribution.
• {version}: A semantic version string.
• {extension}: The name of a PGXN extension.
• {user}: The nickname of a PGXN user.
• {tag}: A tag name, or keyword.
• {stats}: The name of a statistics file. Possible values are:
  • "dist"
  • "extension"
  • "user"
  • "tag"
  • "summary"
• {format}: The format of a file. Possible values are:
  • "html"
  • "txt"
• {+docpath}: The path to a documentation file, minus the file name suffix. That is, "foo/bar", but not "foo/bar.txt".
• {in}: The name of a full text search index. Possible values are:
  • docs
  • dists
  • extensions
  • users
  • tags
• {char}: A single, lowercase ASCII character in the range of a-z.

APIs

The following is a comprehensive list of all available APIs. They are named for their key names in the API index, and of course map to corresponding URI templates. Follow the link to each document to learn about additional parameters and the structure of the returned content.

Mirror APIs

These APIs are offered by all mirror servers and API servers in the network. Consult the documentation for each for how the returned values may differ between mirror and API servers.

• download: Download a distribution zip archive.
• [[readme|readme-api]: Returns the README file from a single release of a distribution.
• [[meta|meta-api]: Returns the META.json describing a single release of a distribution.
• [[dist|dist-api]: Returns JSON describing all releases of distribution.
• [[extension|extension-api]: Returns JSON describing all distributions and releases of an extension.
• user: Returns JSON describing a user and all distributions released by that user.
• tag: Returns JSON listing all distributions releases tagged with a specific tag.
• stats: Returns JSON with statistics on objects managed on the network.
• mirrors: Returns JSON listing all public mirrors in the network.
• spec: Returns a plain text document documenting the latest version of the PGXN Meta Spec supported by the network.

API Server APIs

These APIs are offered only by API servers.

• htmldoc: Returns an HTML snippet for a documentation file.
• search: Provides full-text search of objects on the network. Results are returned in JSON format.
• source: Provides simple access to the contents of a release of a distribution, suitable for browsing in a Web browser.
• userlist: Returns JSON describing PGXN users.

Status Codes

PGXN mirrors and API servers return the following HTTP status codes for all requests:

• 200: Success.
• 400: Bad request: Consult the documentation.
• 404: Not found.
• 503: Service unavailable: Try again later.
• 500: Internal server error: Try again later.

Other Resources

If you have any questions about the PGXN Mirror and API Server APIs, please post them to the PGXN Users list. If you find any bugs in the API, please report them. To follow news about PGXN, subscribe to the blog and the Twitter stream.