view release on metacpan or  search on metacpan

lib/DBIx/Class/Sims/REST.pm  view on Meta::CPAN

      [ 200, [ 'Content-type', 'application/json' ],
        [ encode_json($rv) ],
      ]
    },
  }
}

1;
__END__

=head1 NAME

DBIx::Class::Sims::REST

=head1 SYNOPSIS

In your REST API class:

  package My::Sims::REST

  use base 'DBIx::Class::Sims::REST::MySQL';

  sub get_schema_class { return 'My::Schema::Class' }

  1;

In a rest.cgi file (somewhere):

  use Module::Runtime qw(use_module);
  my $app = use_module('My::Sims::REST')->to_psgi_app;

  use Plack::Builder;

  builder {
    # Or whatever other middleware you want.
    enable "Runtime"; # Adds the X-Runtime header
    $app
  }

Then later:

  plackup <path/to/your/rest.cgi> -p <PORT>

And, finally, in your test (or some library your tests use):

  my $data = {
      databases => [
          {
              database => {
                  name => 'database name',
                  username => 'some username',
                  password => 'some password',
              },
              spec => <DBIx::Class::Sims specification>,
          },
      ],
  };

  my $ua = LWP::UserAgent->new;
  my $req = HTTP::Request->new(POST => 'http://<URL>:<PORT>/sims');
  $req->content(encode_json($data));
  my $res = $ua->request($req);

  return decode_json($res->content);

=head1 PURPOSE

L<DBIx::Class::Sims> provides an easy way to create and populate test data. But,
sometimes, your application isn't built on L<DBIx::Class>. Or Perl. These issues
shouldn't get in the way of using good tools. (Even if your application or test
suite aren't in Perl.)

Assumption: Everything can issue an HTTP request.

Conclusion: The Sims should be available via an HTTP request.

=head1 DESCRIPTION

This is a skeleton base class that provides the basic functionality for a REST
API around L<DBIx::Class::Sims>. By itself, it only takes the request, parses it
out, and invokes a series of methods that have empty implementations. You are
supposed to subclass this class and provide the meat of these methods.

You will have to create a L<DBIx::Class> description of your schema (or, at the
least, the bits you want to be able to sim in your tests). It really isn't that
difficult - there are examples in the test suite for this module.

Once you have all of that, you will need to host this REST API somewhere. Since
its purpose is to aid in testing, a good place for it is in your developers'
Vagrant VMs, and also in the VM you use to run CI tests on.

B<THIS SHOULD NEVER BE MADE AVAILABLE IN PRODUCTION.> If you do so, the problems
you will have are on your head and your head alone. I explicitly and
categorically disavow any and all responsibility for your idiocy if this ends up
in your production environment. Please, do not be stupid.

=head1 REQUEST

The full data structure to be passed via a request is as follows:

  {
      defaults => {
          database => {
              username => '',
              password => '',
              root => {
                  username => '',
                  password => '',
              },
          },
          create => 1,
          deploy => 1,
      },
      databases => [
          {
              database => {
                  username => 'username',
                  password => 'password',
                  name     => 'name',
                  root     => {