Friday, July 16, 2010

Getting piston forms to play nicely with JSON

Critical Update 2012/05/10!!!
Critical Update 2012/05/10!!!
Critical Update 2012/05/10!!!

Except for a critical security patch, django-piston has been unsupported for about 3 years. That is an eternity, and the number of forks to address multiple issues is cause for alarm. Also, the original author has left the project. Because of that, in it's place at this time I recommend django-tastypie. It is up-to-date, has very good documentation, supports OAUTH, and scored second place in the Django Packages thunderdome (it got nearly 3x as many points!). Another tool to consider is Django Rest Framework, which is as good as django-tastypie but lacks the OAUTH support.

Back to the existing blog post...

A commonly used tool by Djangonauts is django-piston, which is designed to make building a REST API easier. It even works with Django forms to provide easily written PUT/POST validation, which should be pretty darn nice. Unfortunately, if you go with django-piston forms validation it doesn't accomodate the JSON (or XML or YAML) requests and if validation fails it responds in HTML. Even more unfortunate, making validation accept and return JSON with PUT/POST requests is not documented.

While one could argue that it is documented in the django-piston docstrings, in my opinion that is not sufficient.

Fortunately while working on a project for Revolution Systems we worked out a solution:

"""
myapi/resource.py

    author: Daniel Greenfeld
    license: BSD

This assumes your API accepts JSON only.
"""

import json

from piston.decorator import decorator
from piston.resource import Resource
from piston.utils import rc, FormValidationError

def validate(v_form, operation='POST'):
    """ This fetches the submitted data for the form 
        from request.data because we always expect JSON data
        It is otherwise a copy of piston.util.validate.
    """
        
    @decorator
    def wrap(f, self, request, *a, **kwa):
        
        # Assume that the JSON response is in request.data
        # Probably want to do a getattr(request, data, None)
        #   and raise an exception if data is not found
        form = v_form(request.data)

        if form.is_valid():
            setattr(request, 'form', form)
            return f(self, request, *a, **kwa)
        else:
            raise FormValidationError(form)
    return wrap

class Resource(Resource):
    
    def form_validation_response(self, e):
        """
        Turns the error object into a serializable construct.
        All credit for this method goes to Jacob Kaplan-Moss
        """
        
        # Create a 400 status_code response
        resp = rc.BAD_REQUEST
        
        # Serialize the error.form.errors object
        json_errors = json.dumps(
            dict(
                (k, map(unicode, v))
                for (k,v) in e.form.errors.iteritems()
            )
        )
        resp.write(json_errors)
        return resp

Usage in handlers.py:

from django import forms

from piston.handler import BaseHandler

from myapp.models import Article

# We use our custom validate rather than piston's default
from myapi.resource import validate

class ArticleForm(forms.Form):
    """ This is best stored in forms.py but we put 
        here for sake of clarity"""

    author      = forms.CharField(required=True)
    title       = forms.CharField(required=True)
    content     = forms.CharField(required=True)

class ArticleHandler(BaseHandler):

    allowed_methods = ('GET', 'POST', 'PUT', 'DELETE', )
    model = Article
                    
    @validate(ArticleForm)
    def create(self, request):
        # Create/POST code goes here. 

    @validate(ArticleForm)
    def update(self, request, id):
        # Update/PUT code goes here. 


Usage in urls.py:

from django.conf.urls.defaults import *

from piston.authentication import HttpBasicAuthentication as auth

# Import our ArticleHandler
from myapi.handlers import ArticleHandler
# Use our custom Resource class instead of piston's default
from myapi.resource import Resource 

article_handler = Resource(ArticleHandler, authentication=auth)

urlpatterns = patterns('',
   url(
        r'^articles/(?P(\d+))$', 
        article_handler,
        { 'emitter_format': 'json' },
        name='api_article'
       ),   
)

Of course, this assumes you are mapping Create/Read/Update/Delete (CRUD) actions to your API.

I'm interested to see other solutions people have used to handle this in django-piston, and what suggestions people have that could improve on the examples I'm supplying here.

6 comments:

Tom said...

Nice. I created an XML mimer for piston so that it could receive XML in the same format that it emits XML which worked well for what I wanted. It's @ http://bitbucket.org/cootetom/xml-mimer/overview

pydanny said...

@Tom,

Do you have the non-patch version of the code?

Ryan Blunden said...

This is absolutely brilliant work. I've had a few challenges getting Django Piston to work and this blog post was immensely useful. Thanks heaps!

Anonymous said...

Hi, I have used your solution partially to extend Resource class of piston, so there is no need to patch the original code. You can have a look at http://blog.mashayev.com/2011/02/19/extend-django-piston-to-render-model-form-error-messages/

Unknown said...

hey, thanks to for setting clear that piston is not developed anymore, that really makes me considering to try another framework... unfortunaly i have to say that the documentation of tastypie is awful especially if you try wo work with non-rel datatsources

pydanny said...

Marty,

If you have problems with the tastypie documentation, might I suggest you do one of the following:

1. Submit a ticket to github.com/toastdriven/django-tastypie/issues and specify where you feel there are specific areas of weakness.

2. If you figure it out, submit it as a pull request to django-tastypie.

Also, there is a MongoEngine wrapper someone wrote for tastypie that you can find at http://www.djangopackages.com/packages/p/django-tastypie-mongoengine/. If MongoDB isn't your nonrel database, then at least you can use that as a baseline for your own implementation.