infrae.rest 1.3
Define a REST API to access and manage Zope 2 content
License: BSD
Keywords: silva cms rest api zope

===========
infrae.rest
===========

``infrae.rest`` provide a simple way to write REST APIs in Zope 2.

API
===

REST component
--------------

``infrae.rest`` provides mainly a base class ``REST`` which behave a
lot like a Grok view::

   from infrae.rest import REST

   class MyAction(REST):
       """My action REST API.
       """

       def POST(self, name, value):
           # Called by POST /content/++rest++myaction&name=foo?value=bar
           return 'Success'

       def GET(self):
           # Called by GET /content/++rest++myaction
           values = self.context.something()
           return self.json_response(values)


You just have to grok your package to make it available.

- You can provide: ``POST``, ``GET``, ``HEAD``, ``DELETE`` requests.

- You can use the directives ``grok.name``, ``grok.require`` and
  ``grok.context`` to configure your REST API. They work exactly like
  on a ``grok.View``.

- If you need, you can manually query a REST component with the help
  of ``infrae.rest.queryRESTComponent``.


Nesting REST component
----------------------

You can nest REST component. In that you should use the grok directive
adapts in order to define which is the parent handler, and the
context::

   from infrae.rest import REST
   from five import grok
   from OFS.Folder import Folder

   class ParentHandler(REST):
       grok.context(Folder)

       def GET(self):
           # Called by GET /folder/++rest++parenthandler
           return u'Hello'


   class ChildHandler(REST):
       grok.adapts(ParentHandler, Folder)

       def GET(self):
           # Called by GET /folder/++rest++parenthandler/childhandler
           return u'Child


RESTWithTemplate component
--------------------------

You can alternatively use the base class ``RESTWithTemplate``. The
only difference is that your class will be associated to a Grok
template automatically.


Repository
==========

Sources can be found in Mercurial at: https://hg.infrae.com/infrae.rest

Changes
=======

1.3 (2013-05-23)
----------------

* Add support for ``static`` on a ``RESTWithTemplate`` component.

* Update tests.

1.2 (2012-09-04)
----------------

* Change registry for handlers from ``zope.component`` to
  ``zeam.component``. This simplify the code base and brings more
  flexibility. Expose ``queryRESTComponent`` function.

* Remove usage of Zope 2 ``shiftNameToApplication``, as this is buggy
  in recent Zope 2 releases.

1.1 (2011-11-07)
----------------

* Add support for nested handlers.

* Add support for ``absoluteURL``, in order to get back the URL of an handler.

* Add a default component that is associated with a Grok template. You
  have to trigger the template rendering yourself.

* An event is triggered when a handler is published. If the handlers
  are nested, the event is only triggered for the last one. You can
  see as publisher after traverse event, except you have access to the
  associated handler that is published.

* We now use only the Python native json module (and no longer
  simplejson).

1.0.1 (2010-10-07)
------------------

* Don't define response as a property to be compatible with other Zope views (as a mixin).

1.0 (2010-07-15)
----------------

* Initial release