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: https://docs.fastly.com/guides/performance-tuning/improving-caching-performance-with-large-files#streaming-miss.
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.
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, http://github.com/cpan-testers/cpantesters-project, http://www.cpantesters.org
Doug Bell preaction@cpan.org
- Breno G. de Oliveira garu@cpan.org
- mohawk2 mohawk2@users.noreply.github.com
- Nick Tonkin 1nickt@users.noreply.github.com
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.