NAME

Cookieville - REST API for your database

VERSION

0.01

DESCRIPTION

Cookieville is a a web application which allow you to inspect and run queries on your SQL database using a REST interface.

This application need a DBIx::Class based schema to work. It will query the result files on disk to gather meta information about the schema instead of looking into the running database.

THIS SERVER IS CURRENTLY EXPERIMENTAL AND WILL CHANGE WITHOUT ANY NOTICE.

SYNOPSIS

  $ COOKIEVILLE_SCHEMA="My::Schema" cookieville daemon --listen http://*:5000

Connection arguments will be read from $HOME/.cookieville. Example:

  $ cat $HOME/.cookieville
  {
    'My::Schema' => [
      'DBI:mysql:database=some_database;host=localhost',
      'dr_who',
      'MostS3cretpassWord',
    ],
  }

TIP: Give .cookieville the file mode 0600 to protect your passwords.

RESOURCES

• GET /

  Returns a description of this application:

    {
      "version": "0.01",
      "source": "https://github.com/jhthorsen/cookieville",
      "resources": {
        "schema_source_list": [ "GET", "/sources" ],
        "schema_for_source": [ "GET", "/:source/schema" ],
        "source_search": [ "GET", "/:source/search?q=:json&limit=:int&order_by:json" ],
        "source_delete": [ "DELETE", "/:source/:id" ],
        "source_patch": [ "PATCH", "/:source/:id" ],
        "source_update_or_insert": [ "PUT", "/:source" ]
      }
    }

  The environment variable COOKIEVILLE_INFO can be used to limit the data returned:

    COOKIEVILLE_INFO=source,resources

• GET /sources

  Returns a list of available sources (resultsets). Example:

    [ "Users", "Posts" ]

• GET /:source/schema

  Returns the schema for the given source.

• GET /:source/search?q=:json&limit=:int&page=:int&order_by=:json

  Does a SELECT from the given source. q will be deserialized and used as the query part.

  limit, page and order_by are optional.

  The return value will be a JSON document containing the rows. Example:

    {
      data: [
        { "id": 1002, "name": "Jan Henning Thorsen", "age": 31 },
        { "id": 3005, "name": "Billy West", "age": 62 }
      ]
    }

  TODO: Make sure integers from the database are actual integers in the result JSON.

  The format .csv is also supported. Example:

    GET /Users.csv?q={"age":31}&order_by=name

• DELETE /:source/:id

  Used to DELETE a single row identified by id.

  The return value will be a JSON document with the number of rows deleted:

    {"n":1}

  NOTE: This will be {"n":0} if the record was already deleted.

• PATCH /:source/:id

  Used to do a (partial) UPDATE of a single row identified by id. The HTTP body must be a JSON structure with the data to update to.

  The return value will have the new document. Example:

    {
      "data": { "id": 1002, "name": "Jan Henning Thorsen", "age": 31 }
    }

  Will return 404 if the given id does not match any records in the database.

• PUT /:source

  Used to INSERT or UPDATE a single row. The HTTP body must be a JSON structure with the data to insert or update.

  The return value will be a JSON document containing all the data for the inserted or updated row. Example:

    {
      "inserted": true, # or false
      "data": { "id": 1002, "name": "Jan Henning Thorsen", "age": 31 }
    }

Error handling

The API will return "200 OK" on success and another error code on failure:

• 400

  Return the document below on invalid input data. message holds a description of what is missing. Example:

    { "message": "Missing (q) query param." }

• 401

  Return the document below on when not authorized. message holds a description of why not. Example:

    { "message": "Invalid token." }

• 404

  Return the document below if the given resource could not be found. message holds a description of what is not found. Examples:

    { "message": "Resource not found" }
    { "message": "No source by that name." }
    { "message": "No matching records in database." }

• 500

    { "message": "Internal server error." }

  Generic error when something awful happens. message might not make any sense. Look at the server log for more details.

Other error codes might be added in future releases.

Queries

The queries (referred to as the "q" query param in the API) are passed on as the first argument to "search" in DBIx::Class.

ATTRIBUTES

connect_args

  $array_ref = $self->connect_args;

Looks in $HOME/.cookieville to find connect args for "schema_class". See "SYNOPSIS" for details.

schema_class

  $class_name = $self->schema_class;

Returns the class name used to connect to the database. This defaults to the environment variable COOKIEVILLE_SCHEMA.

HELPERS

db

  $obj = $self->db;

Returns an instance of "schema_class".

METHODS

setup_routes

Used to setup the "RESOURCES".

startup

Will set up "RESOURCES" and add "HELPERS".

COPYRIGHT AND LICENSE

Copyright (C) 2014, Jan Henning Thorsen

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

AUTHOR

Jan Henning Thorsen - jhthorsen@cpan.org

cpanm Cookieville

perl -MCPAN -e shell
install Cookieville