David E. Wheeler > PGXN-API-v0.16.3 > PGXN::API

Download:
PGXN-API-v0.16.3.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v0.16.3   Source  

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://master.pgxn.org/pgxn/

In a system start script:

  pgxn_api_server --doc-root    /var/www/api \
                  --errors-from oops@example.com \
                  --errors-to   alerts@example.com

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 ^

Constructor

instance

  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

version_string

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

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

Attributes

uri_templates

  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.

doc_root

  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.

source_dir

  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.

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

read_json_from

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

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

write_json_to

  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 bug-PGXN-API@rt.cpan.org.

See Also ^

PGXN::Manager

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.

WWW::PGXN

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

PGXN::Site

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.

PGXN::API::Sync

The implementation for pgxn_api_sync.

PGXN::API::Indexer

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

PGXN::API::Searcher

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

Author ^

David E. Wheeler <david.wheeler@pgexperts.com>

Copyright and License ^

Copyright (c) 2011-2013 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: