View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
David E. Wheeler > PGXN-API-v0.16.2 > PGXN::API



Annotate this POD


View/Report Bugs
Module Version: v0.16.2   Source   Latest Release: PGXN-API-v0.16.5

Name ^

PGXN::API - Maintain and serve a REST API to search PGXN mirrors

Synopsis ^

In a cron job:

  * * * * 42 pgxn_api_sync --root /var/www/api rsync://

In a system start script:

  pgxn_api_server --doc-root    /var/www/api \
                  --errors-from \

Description ^

PGXN is a CPAN-inspired network for distributing extensions for the PostgreSQL RDBMS. All of the infrastructure tools, however, have been designed to be used to create networks for distributing any kind of release distributions and for providing a lightweight static file JSON REST API.

PGXN::API provides a superset of the static file REST API, embellishing the metadata in some files and providing additional APIs, including full-text search and browsable access to all packages on the mirror. Hit the PGXN API server for the canonical deployment of this module. Better yet, read the comprehensive API documentation or use WWW::PGXN if you just want to use the API.

There are two simple steps to setting up your own API server using this module:

And that's it. If you're interested in the internals of PGXN::API or in hacking on it, read on. Otherwise, just enjoy your own API server!

Interface ^



  my $app = PGXN::Manager->instance;

Returns the singleton instance of PGXN::Manager. This is the recommended way to get the PGXN::API object.

Class Method


  say 'PGXN::API ', PGXN::API->version_string;

Returns a string representation of the PGXN::API version.



  my $templates = $pgxn->uri_templates;

Returns a hash reference of the URI templates for the various files stored in the API document root. The keys are the names of the templates, and the values are URI::Template objects. Includes the additional URI templates added by "update_mirror_meta" in PGXN::API::Indexer.


  my $doc_root = $pgxn->doc_root;

Returns the document root for the API server. The default is the www directory in the root directory of this distribution.


  my $source_dir = $pgxn->source_dir;

Returns the directory on the file system where sources should be unzipped, which is just the src subdirectory of doc_root.


  my $mirror_root = $pgxn->mirror_root;

Returns the directory on the file system where the PGXN mirror lives, which is just the mirror subdirectory of doc_root.


  my $data = $pgxn->read_json_from($filename);

Loads the contents of $filename, parses them as JSON, and returns the resulting data structure.


  my $data = $pgxn->write_json_to($filename, $data);

Writes $data to $filename as JSON.

Support ^

This module is stored in an open GitHub repository. Feel free to fork and contribute!

Please file bug reports via GitHub Issues or by sending mail to

See Also ^


The heart of any PGXN network, PGXN::Manager manages distribution uploads and mirror maintenance. You'll want to look at it if you plan to build your own network.

API Documentation

Comprehensive documentation of the APIs provided by both mirror servers and API servers powered by PGXN::API.


A Perl interface over a PGXN mirror or API. Able to read the mirror or API via HTTP or from the local file system.


A layer over the PGXN API providing a nicely-formatted Web site for folks to perform full text searches, read documentation, or browse information about users, distributions, tags, and extensions.


The implementation for pgxn_api_sync.


Does the heavy lifting of processing distributions and indexing them for the API.


Interface for accessing the PGXN::API full text indexes. Used to do the work of the /search API.

Author ^

David E. Wheeler <>

Copyright and License ^

Copyright (c) 2011 David E. Wheeler.

This module is free software; you can redistribute it and/or modify it under the PostgreSQL License.

Permission to use, copy, modify, and distribute this software and its documentation for any purpose, without fee, and without a written agreement is hereby granted, provided that the above copyright notice and this paragraph and the following two paragraphs appear in all copies.

In no event shall David E. Wheeler be liable to any party for direct, indirect, special, incidental, or consequential damages, including lost profits, arising out of the use of this software and its documentation, even if David E. Wheeler has been advised of the possibility of such damage.

David E. Wheeler specifically disclaims any warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The software provided hereunder is on an "as is" basis, and David E. Wheeler has no obligations to provide maintenance, support, updates, enhancements, or modifications.

syntax highlighting: