/ 
CPAN-Testers-API-0.025
River stage zero No dependents
/ CPAN::Testers::API

NAME

CPAN::Testers::API - REST API for CPAN Testers data

VERSION

version 0.025

SYNOPSIS

$ cpantesters-api daemon
Listening on http://*:5000

DESCRIPTION

This is a REST API on to the data contained in the CPAN Testers database. This data includes test reports, CPAN distributions, and various aggregate test reporting.

METHODS

schema

my $schema = $c->schema;

Get the schema, a CPAN::Testers::Schema object. By default, the schema is connected from the local user's config. See "connect_from_config" in CPAN::Testers::Schema for details.

startup

# Called automatically by Mojolicious

This method starts up the application, loads any plugins, sets up routes, and registers helpers.

render_error

return $c->render_error( 400 => 'Bad Request' );
return $c->render_error( 400, {
    path => '/since',
    message => 'Invalid date/time',
} );

Render an error in JSON like other OpenAPI errors. The first argument is the HTTP status code. The remaining arguments are a list of errors to report. Plain strings are turned into one-element hashrefs with a message key. Hashrefs are used as-is.

The resulting JSON looks like so:

{
    "errors":  [
        {
            "path": "/",
            "message": "Bad Request"
        }
    ]
}

{
    "errors":  [
        {
            "path": "/since",
            "message": "Invalid date/time"
        }
    ]
}

stream_rs

$c->stream_rs( $rs, $processor );

Stream a DBIx::Class::ResultSet object to the browser. This prevents problems with proxy servers and CDNs timing out waiting for data. This uses "write_chunk" in Mojolicious::Controller to transfer a chunked response. If there are no results in the ResultSet object, this method returns a 404 error.

$processor is an optional subref that allows for processing each row before it is written. Use this to translate column names or values into the format the API expects.

For this to work usefully behind Fastly, we also need to enable streaming miss so that Fastly streams the data to the end-user as it gets it: https://docs.fastly.com/guides/performance-tuning/improving-caching-performance-with-large-files#streaming-miss.

CONFIG

This application can be configured by setting the MOJO_CONFIG environment variable to the path to a configuration file. The configuration file is a Perl script containing a single hash reference, like:

# api.conf
{
    broker => 'ws://127.0.0.1:5000',
    schema => 'dbi:SQLite:api.db',
}

The possible configuration keys are below:

broker

The URL to a Mercury message broker, starting with ws://. This broker is used to forward messages to every connected user.

schema

The DBI connect string to give to CPAN::Testers::Schema. If not specified, will use "connect_from_config" in CPAN::Testers::Schema.

LOCAL TESTING

To run an instance of this for local testing, create an api.conf file to configure a SQLite schema:

# api.conf
{
    schema => 'dbi:SQLite:api.sqlite3'
}

For the CPAN::Testers::Schema to work with SQLite, you will need to install an additional CPAN module, DateTime::Format::SQLite.

Once this is configured, you can deploy a new, blank database using cpantesters-api eval 'app->schema->deploy'.

Now you can run the API using cpantesters-api daemon.

SEE ALSO

Mojolicious, Mojolicious::Plugin::OpenAPI, CPAN::Testers::Schema, http://github.com/cpan-testers/cpantesters-project, http://www.cpantesters.org

AUTHOR

Doug Bell <preaction@cpan.org>

CONTRIBUTORS

  • Breno G. de Oliveira <garu@cpan.org>

  • mohawk2 <mohawk2@users.noreply.github.com>

  • Nick Tonkin <1nickt@users.noreply.github.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Doug Bell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.