pyramid_restler
===============

Overview
--------

pyramid_restler is a somewhat-opinionated toolkit for building RESTful Web
services and applications on top of the Pyramid framework. Essentially, it
routes HTTP requests to Pyramid views. These views interact with model
entities via a uniform context interface and then respond with appropriate
status codes and entity representations.

Routes
------

A Pyramid configuration directive is provided that makes generating the
various routes and views for an entity easy::

    config.add_restful_routes('thing', ThingModel)

This generates routes similar to those generated by `Mapper.resource` in the
Routes package::

    Request method /pattern => route name => view method => context method

    GET /{name} => get_{name}_collection => get_collection() => get_collection()
    GET /{name}.{renderer} => get_{name}_collection => get_collection() => get_collection()
    GET /{name}/{id} => get_{name} => get_member() => get_member(id)
    GET /{name}/{id}.{renderer} => get_{name} => get_member() => get_member(id)
    POST /{name} => create_{name} =>  create_member() => create_member(**data)
    PUT /{name}/{id} => update_{name} => update_member() => update_member(id, **data)
    DELETE /{name}/{id} => delete_{name} => delete_member() => delete_member(id)

Views
-----

RESTful views are implemented as a standard set of methods in view classes.
The :class:`pyramid_restler.interfaces.IView` interface describes how such
classes should be implemented. A default view class,
:class:`pyramid_restler.view.RESTfulView`, is provided, which should be
sufficient for many applications.

Model
-----

Views interact with a context, which is a wrapper around some kind of back
end model entity. A common example of such an entity is a SQLAlchemy ORM
class; a :class:`pyramid_restler.model.SQLAlchemyORMContext` class is
provided.

The purpose of the context layer is to provide a uniform interface to any
kind of back end model. This way, the view layer can be written in a generic
manner. This design helps to keep concerns appropriately separated: the view
layer should handle parsing HTTP requests and generating HTTP responses; the
context layer should handle interacting with and converting data from the
model.

More Info
---------

.. toctree::
   :maxdepth: 1

   api

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`