/ 
PGXN-API-v0.20.2
River stage zero No dependents
/ PGXN::API

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:

  • pgxn_api_sync

    This script syncs to a PGXN mirror via rsync and processes newly-synced data to provide the additional data and APIs. Any PGXN mirror will do. If you need to create your own network of mirrors first, see PGXN::Manager. Consult the pgxn_api_sync documentation for details on its (minimal) options.

  • pgxn_api_server

    A Plack server for the API. In addition to the usual plackup options, it has a few of its own:

    --doc-root

    The path to use for the API document root. This is the same directory as you manage via pgxn_api_sync in a cron job. Optional. If not specified, it will default to a directory named www in the parent directory above the PGXN directory in which this module is installed. If you're running the API from a Git checkout, that should be fine. Otherwise you should probably specify a document root or you're you'll never be able to find it.

    --errors-to

    An email address to which error emails should be sent. In the event of an internal server error, the server will send an email to this address with diagnostic information.

    --errors-from

    An email address from which alert emails should be sent.

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