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


version 0.025


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


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.



    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.


    # Called automatically by Mojolicious

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


    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"


    $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:


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://',
        schema => 'dbi:SQLite:api.db',

The possible configuration keys are below:


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


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


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.


Mojolicious, Mojolicious::Plugin::OpenAPI, CPAN::Testers::Schema,,


Doug Bell <>


  • Breno G. de Oliveira <>

  • mohawk2 <>

  • Nick Tonkin <>


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.