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.

Entry Point

The entry point for all PGXN mirrors and API Servers is the index at the root of the mirror server or API URL. It maps all other APIs to URI templates. Examples:

• PGXN Master Mirror
• PGXN API Server

All clients must access this URI before any other in order to be able to construct the URIs for all other API calls. This is the only file that is guaranteed to be available at the same address at all times. It's the entry point for all API access, and the lookup table for all other API URIs. If you plan to access the PGXN API, the index API documentation is the first thing you should read after this introduction.

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 powered 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.

Data Types

JSON responses may contain values in one or more of the following data types:

• String: A simple string value.
• Number: A simple numeric value.
• Date: An string containing an ISO-8601 date in the UTC time zone, formatted as [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z. Example: "2011-04-20T23:47:22Z".
• SemVer: A string containing a semantic version string.
• Array: An array of one or more other values of any kind.
• Object: A list of key/value pairs, where the keys are strings and the values may be any other type.

APIs

The following is a comprehensive list of all available APIs. Other than the index API, all are named for index key names. 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.

• index: Returns a JSON lookup table for all other API URIs.
• download: Download a distribution zip archive.
• readme: Returns the README file from a single release of a distribution.
• meta: Returns the META.json describing a single release of a distribution.
• dist: Returns JSON describing all releases of distribution.
• extension: 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 listing 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.

Headers

PGXN API servers provide a special HTTP header not provided by mirror servers. The header is X-PGXN-API-Version and identifies the release of PGXN::API that's serving the API:

> curl -I http://api.pgxn.org/
HTTP/1.1 200 OK
Date: Wed, 27 Apr 2011 00:00:39 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 679
Last-Modified: Mon, 25 Apr 2011 18:15:31 GMT
X-PGXN-API-Version: v0.12.5

Use this header to distinguish API servers from mirror servers. In the future it may be used to ascertain what API features are available, although it should not be necessary, since all APIs are identified by the index API.