Package: devil
# Simple REST framework for Django[Devil][13] aims to be simple to use REST framework for Django. Devil isinfluenced by [piston][1].## Key Characteristics- `Resource` is the key concept, everything builds around it.- Builtin content negotiation (parsers / formatters).- Gets out of your way- You can use additional features but you don't need to.- Everything is optional and works with default values.- Simple to get started.- Flexible access control based on Django's users, groups andpermissions.- Ability to assign CRUD operations per resource foreach user (or group)- devil will auto-generate necessary permissions into the DB- You can use Django's admin interface to assign permissions to users and groups- After this devil automatically picks up `request.user` and performs authorization- Intentionally doesn't give you CRUD for free as piston does- We can add this option later if it's concidered useful, but:- This rarely works for legacy systems anyway- For anything bigger, it's usually a good idea to decouplemodel and representation- Ability to define representation using Django's forms- Automatic validation of incoming/outgoing data- Automatic documentation generation (_Not implemented yet_)## Table of Contents- [Installation](#installation)- [Quick Example](#quick-example)- [Step by Step Instructions](#step-by-step-instructions)- [URL Dispatching](#url-dispatching)- [Method Dispatching](#method-dispatching)- [Content Type Negotiation](#content-type-negotiation)- [Dealing with Data](#dealing-with-data)- [HTTP Responses](#http-responses)- [Defining Representations](#defining-representations)- [Using Object Factories](#using-object-factories)- [Auto-generated Documentation](#auto-generated-documentation)- [Configuration](#configuration)- [License](#license)## Installationpip install devilSource code can be found at [GitGub][7]## Quick Exampleresources.py:```pythonfrom devil.resource import Resourceclass MyTestResource(Resource):def get(self, request):return {'jedi': 'luke'}```urls.py:```pythonfrom django.conf.urls.defaults import patterns, urlfrom devil.resource import Resourceimport resourcesmytestresource = resources.MyTestResource()urlpatterns = patterns('',url(r'^test', mytestresource),)```curl:curl http://localhost:8000/test?format=json> GET /contact/?format=json HTTP/1.1> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4> Host: localhost:8000> Accept: */*>< HTTP/1.0 200 OK< Date: Tue, 14 Feb 2012 09:35:02 GMT< Server: WSGIServer/0.1 Python/2.7.1< Content-Type: application/json; charset=utf-8<{"jedi": "luke"}Anoher simple example is available [here][13]## Step by Step Instructions$ pip install devil$ django-admin.py startproject phone_book$ cd phone_book$ python manage.py startapp contactscontacts/resources.py:```pythonfrom devil.resource import Resourceclass Contact(Resource):def get(self, request, *args, **kw):return {'name': 'Luke Skywalker'}```urls.py:```pythonfrom django.conf.urls.defaults import patterns, urlfrom contacts import resourcescontacts_resource = resources.Contact()urlpatterns = patterns('',url(r'contact', contacts_resource),)```start the server and in the console say (or you can use a browser):$ python manage.py runserver$ curl http://localhost:8000/contact?format=jsonor if you want to be more HTTP friendly:$ curl http://localhost:8000/contact -H 'Accept: application/json'A more complete example can be found under [examples/userdb][14]. See the READMEfor instructions on running the example and how to examine the code.## URL DispatchingThe relationship between URLs and RESTful resources is _one to many_. That is,one resource may have several URLs mapped to it. Conversely, one URL is alwaysmapped into a single resource. Devil uses Django's built in [URLdispatching][8] to define these mappings. If you are familiar with Django'sterms and concepts the resources in Devil become the _views_ of Django.Say you define your resources in a module called `resources`. Then in your`urls.py` file you would instantiate and map your resources to URLs, like so:```pythonuser_resource = resources.UserResource()urlpatterns = patterns('',url(r'/user', user_resource),)```And to define aliases, you can just add new mappings to the same resource:```pythonurlpatterns = patterns('',url(r'/user', user_resource),url(r'/jedi', user_resource),url(r'/sith', user_resource),)```You can use Django's built-in regexp features like named parameters:```pythonurlpatterns = patterns('',url(r'/user(?P<id>\d{1,7})?', user_resource),)```In this case, the `id` property would be available in the resource method:```pythonclass UserResource(Resource):def get(self, request, id, *args, **kw):print id```or```pythonclass UserResource(Resource):def get(self, request, *args, **kw):print kw['id']```## Method DispatchingDevil maps the HTTP request methods into functions of the resource directly.So, if Devil receives an HTTP POST request, it will try and find an instancemethod called `post` in the resource and invoke it. If the resource doesn'tdefine `post` method, Devil will automatically return `405 Mehod Not Allowed`to the client. The signature for the method for `PUT` and `POST` requests is:```pythondef post(self, data, request):```and for others methods:```pythondef get(self, request):```so, PUTs and POSTs will have additional `data` attribute that contains the(possibly parsed) content body of the request. Also, bear in mind thatfunction parameters may also include named parameters from url mappings.## Content Type NegotiationDevil uses the terms `parser` and `formatter` for data decoding and encodingrespectively. They are collectively referred to as data `mappers`. Devil usesdata mappers to parse all data that comes in with `PUT` and `POST` requests(e.g. JSON, XML or plaintext). Similarly, devil uses data mappers toautomatically format all outgoing data when it is present. The mapper to be usedfor a given request can be defined in one of the following places (note thatthis list is not sorted by precedence):- In the URL:- either with `?format=json`- or with `.json` suffix- HTTP [Accept][2] header. The Accept header supports the full format,as in: `Accept: audio/*; q=0.2, audio/basic`- HTTP [Content-Type][3] header (meaningful only for `PUT` and `POST`)- A resource may define its own mapper which will take precedence overanything else- define `mapper` in your derived `Resource` class (see [examples][4])- A resource may define a default mapper that will be used if the clientspecifies no content type- define `default_mapper` in your derived `Resource`class (see [examples][4])- Application may define one system wide default mapper by registering amapper with content type `*/*`If the client specifies a content type that is not supported, devil respondswith `406 Not Acceptable`. Out of the box, devil supports `plain/text`,`application/json` and `text/xml`. You can register more mappers for yourapplication of course. It should be noted that the built-in XML mapper hassome restrictions (see the [docstring][5]).Following picture formally defines how a correct formatter is chosen forencoding the outgoing data:![Selecting a formatter](https://github.com/wuher/devil/raw/master/doc/select-formatter.pdf "Selecting a formatter")Likewise, the next picture defines how a correct parser is chosen for theincoming (via `PUT` or `POST`) data:![Selecting a parser](https://github.com/wuher/devil/raw/master/doc/select-parser.pdf "Selecting a parser")See the [docstrings][6] in the `DataMapper` class and the [exampleresources][4] in tests for instructions on how to implement your own mappers.## Dealing with DataOnce the appropriate data mapper has been chosen, devil can performdecoding for the incoming data and encoding for the outgoing data. Forexample, if a json mapper is chosen your `post` and `get` functions would looksomething like this (in terms of data passing):$ curl http://localhost:8000/contact -X POST -d '{"name": "Darth Maul", "age": 24}' -H 'Content-Type: application/json'```pythondef post(self, data, request):# data is available as a python dict in the data parameterprint data['name']       # Darth Maulprint type(data['age'])  # <type 'int'>```$ curl http://localhost:8000/contact/1 -X GET -H 'Accept: application/json'```pythondef get(self, request):# you can return a python dictionaryreturn {'name': 'Yoda','age': '876',}```Devil's built-in json and xml mappers will convert to and from pythondictionaries and lists. However, the built-in text (`text/plain`) mapper willonly convert between strings and unicode objects.## HTTP ResponsesA resource (that is, any of its post/get/put/delete methods) may return followingvalues:- dictionary- list- string- `None`- Devil's `http.Response`- Django's `HttpResponse`If the resource returns Django's `HttpResponse`, devil doesn't touch thereturn value at all but just passes it on to the client. If the return type isany of the other five, devil tries to encode the data using the appropriatemapper. Furthermore, devil's `Response` object provides a way for the resourceto include HTTP response code and headers along with the data. Devil willautomatically use response code `200 OK` in cases where the response codeisn't explicitly defined by the resource. Also, devil will automatically add`Content-Type` HTTP header based on the used data mapper.Error situations may be handled using exceptions defined in `devil.errors`package. So whenever there's an error situation and you want to return a certainresponse code, you can raise a `HttpStatusCodeError` and devil willcatch it and turn it into appropriate HTTP response object.```pythonfrom devil import errorsdef post(self, data, request):if data['age'] > 50:# too oldraise errors.BadRequest("you're too old")```In the example, the client would receive `400 BAD REQUEST` with the string`"you're too old"` in the body whenever the age is above 50.## Defining RepresentationsDevil uses Django's [form fields][15] to define representations. By definingrepresentation for your resource, you gain three advantages: automatic datavalidation, possibility to use object factories to automatically create pythonobjects from your data and the possibility to have [auto-generated documentation](#auto-generated-documentation) for your resources. The easiest way to define arepresentation for your resource is to subclass from [Devil's Representationclass][17] and use fields defined in [Django][15] and [Devil][18] to define allthe properties.Following example shows a simple representation using Django's form fields:```pythonfrom django import formsfrom devil import Representationclass UserRepresentation(Representation):username = forms.CharField(max_length=30)joined = forms.DateField(input_formats='%Y-%m-%d')```Devil provides couple of handy fields for defining more complex representations,mainly `NestedField` and `ListField`. These can be used for speficying compositeand collection fields respectively:```pythonfrom devil.fields import ListField, NestedField, EnumFieldclass EmailAddress(NestedField):email = forms.EmailField()type = forms.CharField(required=False)class UserRepresentation(Representation):username = forms.CharField(max_length=30)joindate = forms.DateField(input_formats=('%Y-%m-%d',))emailAddresses = EmailAddress()accountType = EnumField('root', 'novice', 'intermediate')tags = ListField(forms.CharField(max_length=20), required=False)```The `EmailField` defined here will be reusable in any representation that embedsemail addresses. The `UserRepresentation` on the other hand, is a completerepresentation that can be used in a resource to perform automatic datavalidation. To see how to put `UserRepresentation` into use, see[configuration](#representation).## Using object factoriesAfter a [data mapper](#dealing-with-data) has converted the data into pythondictionary, an object factory may further convert the dictionary into pythonobject. Against common convention for implementing factories, Devil's[factory][16] also provides `serialize()` function which is the counteroperation of `create()`.Factory uses [representation](#defining-representations) object as aspecification when performing object creation and serialization. Normally a_field_ speficied in the representation knows how to marshal/unmarshal itselfbut if not, a subclassed factory may provide `create_foo()` and`serialize_foo()` functions to provide custom creation/serialization of a field(`foo` in our example). Following example demonstrates the definition of`UserFactory`.```pythonfrom devil import Factoryclass User(object):passclass UserFactory(Factory):klass = Userspec = UserRepresentation()```An example of manually using `UserFactory`:```pythontestdata = {'username': 'jedi','joindate': '2012-01-18','emailAddress': {'email': 'jedi@rebillion.net','type': 'work',},'accountType': 'root','tags': ['jedi', 'active', 'rebel'],}factory = UserFactory()user = factory.create(testdata)print user.username  # 'jedi'print user.joindate  # datetime.date(2012, 1, 18)print user.emailAddress.email  # 'jedi@rebillion.net'```To see how to instruct Devil to automatically convert incoming data into pythonobjects using factories, see [configuration](#factory).Factories also support name mangling of properties. For example:emailAddress -> email_addressemail_address -> emailAddressThis is achieved by providing ``alias`` property for a field. For Example:```pythonclass UserRepresentation(Representation):emailAddress = EmailField(alias='email_address')```This definition wouldn't have any affect on data when in serialized format. Thatis, in JSON or in dictionary the property name is still `emailAddress`. However,when the field is present in python object (i.e. after object has been createdwith `factory.create()` or when it is given to `factory.serialize()`) the nameof the property is `email_address`.## Auto-generated Documentation**NOTE** This is still a work in progress but there is a very bare (but working)implementation in the [doc branch][16].Basically, by subclassing your resources from `DocumentedResource` instead of`Resource` you add support for auto- generated documenatation. When clientprovides `_doc` in the query string of the request, a documentation is generatedinstead of the actual method being executed. The documentation includes:- docstring of the implementing resource-class- all supported methods and their docstrings- representations (if defined) and their constraints## ConfigurationResources in Devil can be configured by overriding any of the following classproperties defined in the `devil.Resource` class:```pythonclass Resource(object):access_controller = Noneallow_anonymous = Trueauthentication = Nonerepresentation = Nonepost_representation = Nonefactory = Nonepost_factory = Nonedefault_mapper = Nonemapper = None```It is usually a good idea to derive `devil.Resource` and use the derived classas a base class for your project's resources. That way, you only need to definethese configurations once. The values shown above are the default values that areused if not overridden.### representationWhen defined, this representation will be used for validating both, incoming andoutgoing data. For example: `representation = UserRepresentation()`. Moreinformation on representations is available [here](#defining-representations)### post_representationWhen defined, this representation will be used for validating client-data insidea POST request. If not defined `representation` will be used for POST requeststoo. `post_representation` will never be used for validating outgoing data (i.e.data returned to the client).### factoryWhen defined, Devil uses this factory to automatically convert incoming datainto python objects and outgoing objects into serialized format. An exampledefinition looks like this: `factory = UserFactory()`. More information onfactories is available [here ](#using-object-factories).### post_factoryWhen defined, this factory will be used for creating a python object from datainside a POST request. If not defined, `factory` will be used for POST requeststoo. `post_factory` will never be used for serializing outgoing data.### authenticationDefines the authentication handler. When provided, it should be an object thathas a function called `authentication`. This function takes only oneparemeter: the request object. The function should raise`devil.errors.Unauthorized` if the request cannot be authorized otherwise itmust populate the `request.user` property.Instead of implementing your own authentication you are free to use devil'sHTTP basic authentication or one of Django's authentication middlewares. Touse Devil's authentication, you can simply add this to your resource class:```pythonfrom devil.auth import HttpBasicclass MyResource(Resource):authentication = HttpBasic()```### allow_anonymousIf the resource allows anonymous access, set this to `True` (default). Note,that this is different from `authentication` as you can turn authentication onbut still allow anonymous access (for example with limited access).### access_controllerIf `access_controller` is set, devil uses it to authorize requests. The valueof `access_controller` must be an object that has a method called`check_perm`. This method takes two parameters: the request object and theresource that is being queried. If the request is permitted, the functionshould return nothing. However, if the request is not permitted, the functionshould raise `devil.errors.Forbidden`.While you are free to implement your own access controller, devil comes withan access controller based on Django's _users_, _groups_ and _permissions_. Tomake use of it, you would say this in your resource code:```pythonfrom devil.resource import Resourcefrom devil.perm.acl import PermissionControllerclass MyResource(Resource):access_controller = PermissionController()```After this, all requests to `MyResource` will be authorized based on the userwho sent the request and the method that was used. So, each resource has fourpossible permissions associated with it: `post`, `get`, `put` and `delete`.Devil will automatically check that the user (or the user's group) making therequest has appropriate permission to access the resource.Devil can automatically add all necessary permissions into the database butyou (or the site administrator) will need to assign these permissions forusers (or groups). To have devil populate all possible permissions into thedatabase you need to tell devil what are the resources you want to protect andthen use `syncdb` to insert them. For all this, you would first add two thingsinto your Django `settings.py` file:1. `ACL_RESOURCES` to define your protected resources2. `devil.perm` among `INSTALLED_APPS`For example:```pythonACL_RESOURCES = ('myproject.myapp.urls.acl_resources',)INSTALLED_APPS = ('devil.perm',)```Now, you also need to have your protected resources as a list in the `urls.py`file. For example:```pythonmyresource = MyResource()acl_resources = (myresource,)urlpatterns = (url(r'^test', myresource),)```After this, you can run `python manage.py syncdb` and have devil to insert allnecessary permissions into the database. To be exact, devil inserts them intoDjango's `auth_permission` table. The format for the permission name is`prefix_resourcename_method`. The `prefix` is "resource", the `resourcename`is whatever your resource class´ `name()` function returns and `method` is therequest method (i.e. "post", "get", "put" or "delete"). If you haven'toverridden the `name()` function in your resource class, it returns the nameof the class with CamelCase converted to slashes. So, in our example runningthe `syncdb` would generate following four permissions into the database:- "`resource_my/resource_post`"- "`resource_my/resource_get`"- "`resource_my/resource_put`"- "`resource_my/resource_delete`"Now, you are ready to assign these permissions to your users or groups byusing the Django [admin interface][9].**Few notes:**- Devil's access controller depends on the `request.user` property.This means that the request must have been authenticated before itlands to the access controller. The easiest way to handleauthentication is to use devil's HTTP basic authentication or one ofDjango's authentication middlewares.- `request.user` may not be Django's `AnonymourUser`- If the user making the request is a [super user][10], permission isalways granted.- The user needs to be [active][11] in order to get access to any resourcethat is protected by devin's access controller.- Devil's access controller uses Django's [get_all_permissions][12] functionto figure out whether the user has the permission.## License(The MIT License)Copyright (c) 2012 Janne KuuskeriPermission is hereby granted, free of charge, to any person obtaininga copy of this software and associated documentation files (the'Software'), to deal in the Software without restriction, includingwithout limitation the rights to use, copy, modify, merge, publish,distribute, sublicense, and/or sell copies of the Software, and topermit persons to whom the Software is furnished to do so, subject tothe following conditions:The above copyright notice and this permission notice shall beincluded in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OFMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANYCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THESOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.[1]:https://bitbucket.org/jespern/django-piston/wiki/Home[2]:http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1[3]:http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17[4]:https://github.com/wuher/devil/blob/master/test/deviltest/simple/resources.py[5]:https://github.com/wuher/devil/blob/master/devil/mappers/xmlmapper.py[6]:https://github.com/wuher/devil/blob/master/devil/datamapper.py[7]:https://github.com/wuher/devil[8]:https://docs.djangoproject.com/en/dev/topics/http/urls/[9]:https://docs.djangoproject.com/en/dev/ref/contrib/admin/[10]:https://docs.djangoproject.com/en/dev/topics/auth/#django.contrib.auth.models.User.is_superuser[11]:https://docs.djangoproject.com/en/dev/topics/auth/#django.contrib.auth.models.User.is_active[12]:https://docs.djangoproject.com/en/dev/topics/auth/#django.contrib.auth.models.User.get_all_permissions[13]:http://wuher.github.com/devil/[14]:https://github.com/wuher/devil/tree/master/example/userdb[15]:https://docs.djangoproject.com/en/dev/ref/forms/fields/[16]:https://github.com/wuher/devil/tree/doc[17]:https://github.com/wuher/devil/blob/doc/devil/fields/representation.py[18]:https://github.com/wuher/devil/blob/master/devil/fields/factory.py