Home

The PGXN API

PGXN is a set of infrastructure tools for creating and managing a lightweight, distributed network of source code releases. It's modeled on Perl's CPAN and was originally designed for distributing PostgreSQL extensions on pgxn.org.

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 the API and by PGXN mirror servers.

Introduction

Because PGXN distributes metadata to all mirrors in the form of JSON files, every mirror in the network functions as a lightweight API server. Most of what an API client may want can be found on mirrors, including information about the latest release of an extension and how to find, download, and verify it.

PGXN API servers provide a superset of that functionality. They serve all the same APIs, though many of them are augmented with additional data. But they also provide additional APIs not supported by mirrors, including a [[full-text search|search-api]]. The API server API is most useful for building web applications on PGXN, such as the canonical PGXN site, which is just a thin wrapper around the API.

If you're interested in hacking against the mirror or API server APIs, you've come to the right place. This wiki is the central repository documenting these APIs and how to use them.

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.

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.