skip to navigation
skip to content

Not Logged In

sandman 0.5

Automated REST APIs for existing database-driven systems

Package Documentation

Latest Version: 0.9.2


|Build Status| |Coverage Status| |Stories in Ready|


`Sandman documentation <>`__

**sandman** "makes things REST". Have an existing database you'd like to
expose via a REST API? Normally, you'd have to write a ton of
boilerplate code for the ORM you're using, then integrate that into some
web framework.

I don't want to write boilerplate.

Here's what's required to create a RESTful API service from an existing
database using **sandman**:

.. code:: python

    from sandman import app, db

    app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///chinook'

    from sandman.model import register, Model

    class Artist(Model):
        __tablename__ = 'Artist'

    class Album(Model):
        __tablename__ = 'Album'

    class Playlist(Model):
        __tablename__ = 'Playlist'

    register((Artist, Album, Playlist))

Let's start our new service and make a request. While we're at it, lets
make use of Sandman's awesome filtering capability by specifying a
filter term:

.. code:: zsh

    > python &
    * Running on

    > curl GET "http://localhost:5000/artists?Name=AC/DC"

.. code:: json

        "resources": [
                "ArtistId": 1,
                "Name": "AC/DC",
                "links": [
                        "rel": "self",
                        "uri": "/artists/1"

All of that, including filtering/searching, is automagically available
from those 10 measly lines of code.

Oh, that's not enough? You also want a Django-style admin interface
built automatically? Fine. Add one more line to the list of models to
get access to this:

.. figure:: /docs/images/admin_tracks_improved.jpg
   :alt: improved admin interface screenshot

   improved admin interface screenshot
With **sandman**, (almost) zero boilerplate code is required. Your
existing database structure and schema is introspected and your database
tables magically get a RESTful API and admin interface. For each table,
Sandman creates:

-  proper endpoints
-  support for a configurable set of HTTP verbs

   -  GET
   -  POST
   -  PATCH
   -  PUT
   -  DELETE

-  responses with appropriate ``rel`` links automatically
-  foreign keys in your tables are represented by link
-  custom validation by simply defining ``validate_<METHOD>`` methods on
   your Model
-  explicitly list supported methods for a Model by setting the
   ``__methods__`` attribute
-  customize a Models endpoint by setting the ``__endpoint__`` method
-  essentially a HATEOAS-based service sitting in front of your database

*Warning: Sandman is still very much a work in progress. Use it at your
own risk. It's also often changing in backwards incompatible ways.*


``pip install sandman``


You'll need to create one file with the following contents (which I call

.. code:: python

    from sandman.model import register, Model

    # Insert Models here
    # Register models here
    # register((Model1, Model2, Model3))
    # or
    # register(Model1)
    # register(Model2)
    # register(Model3)

    from sandman import app, db
    app.config['SQLALCHEMY_DATABASE_URI'] = '<your database connection string (using SQLAlchemy)>'

Then simply run

.. code:: bash


and try curling your new RESTful API!

Example Application

Take a look in the ``sandman/test`` directory. The application found
there makes use of the `Chinook <>`__
sample SQL database.

Coming Soon

-  Authentication

.. |Build Status| image::
.. |Coverage Status| image::
.. |Stories in Ready| image::
File Type Py Version Uploaded on Size
sandman-0.5.tar.gz (md5) Source 2013-12-20 14KB
  • Downloads (All Versions):
  • 313 downloads in the last day
  • 11457 downloads in the last week
  • 18347 downloads in the last month