Extending Restless¶

Restless is meant to handle many simpler cases well & have enough extensibility to handle more complex API tasks.

However, a specific goal of the project is to not expand the scope much & simply give you, the expert on your API, the freedom to build what you need.

We’ll be covering:

Custom endpoints
Customizing data output
Adding data validation
Providing different serialization formats

Custom Endpoints¶

Sometimes you need to provide more than just the typical HTTP verbs. Restless allows you to hook up custom endpoints that can take advantage of much of the Resource.

Implementing these views requires a couple simple steps:

Writing the method
Adding to the Resource.http_methods mapping
Adding to your URL routing

For instance, if you wanted to added a schema view (/api/posts/schema/) that responded to GET requests, you’d first write the method:

from restless.dj import DjangoResource
from restless.resources import skip_prepare


class PostResource(DjangoResource):
    # The usual methods, then...

    @skip_prepare
    def schema(self):
        # Return your schema information.
        # We're keeping it simple (basic field names & data types).
        return {
            'fields': {
                'id': 'integer',
                'title': 'string',
                'author': 'string',
                'body': 'string',
            },
        }

The next step is to update the Resource.http_methods. This can either be fully written out in your class or (as I prefer) a small extension to your __init__...:

from restless.dj import DjangoResource
from restless.resources import skip_prepare


class PostResource(DjangoResource):
    # We'll lightly extend the ``__init__``.
    def __init__(self, *args, **kwargs):
        super(PostResource, self).__init__(*args, **kwargs)

        # Add on a new top-level key, then define what HTTP methods it
        # listens on & what methods it calls for them.
        self.http_methods.update({
            'schema': {
                'GET': 'schema',
            }
        })

    # The usual methods, then...

    @skip_prepare
    def schema(self):
        return {
            'fields': {
                'id': 'integer',
                'title': 'string',
                'author': 'string',
                'body': 'string',
            },
        }

Finally, it’s just a matter of hooking up the URLs as well. You can do this manually or (once again) by extending a built-in method.:

# Add the correct import here.
from django.conf.urls import patterns, url

from restless.dj import DjangoResource
from restless.resources import skip_prepare


class PostResource(DjangoResource):
    def __init__(self, *args, **kwargs):
        super(PostResource, self).__init__(*args, **kwargs)
        self.http_methods.update({
            'schema': {
                'GET': 'schema',
            }
        })

    # The usual methods, then...

    # Note: We're using the ``skip_prepare`` decorator here so that Restless
    # doesn't run ``prepare`` on the schema data.
    # If your custom view returns a typical ``object/dict`` (like the
    # ``detail`` method), you can omit this.
    @skip_prepare
    def schema(self):
        return {
            'fields': {
                'id': 'integer',
                'title': 'string',
                'author': 'string',
                'body': 'string',
            },
        }

    # Finally, extend the URLs.
    @classmethod
    def urls(cls, name_prefix=None):
        urlpatterns = super(PostResource, cls).urls(name_prefix=name_prefix)
        return urlpatterns + patterns('',
            url(r'^schema/$', cls.as_view('schema'), name=cls.build_url_name('schema', name_prefix)),
        )

Note

This step varies from framework to framework around hooking up the URLs/routes. The code is specific to the restless.dj.DjangoResource, but the approach is the same regardless.

You should now be able to hit something like http://127.0.0.1/api/posts/schema/ in your browser & get a JSON schema view!

Customizing Data Output¶

There are three approaches to customizing your data ouput.

The built-in Preparer/FieldsPreparer (simple)
Overriding restless.resources.Resource.prepare() (happy medium)
Per-method data (flexible but most work)

Fields¶

Using FieldsPreparer is documented elsewhere (see the Restless Tutorial), but the basic gist is that you create a FieldsPreparer instance & assign it on your resource class. It takes a fields parameter, which should be a dictionary of fields to expose. Example:

class MyResource(Resource):
    preparer = FieldsPreparer(fields={
        # Expose the same name.
        "id": "id",
        # Rename a field.
        "author": "username",
        # Access deeper data.
        "type_id": "metadata.type.pk",
    })

This dictionary is a mapping, with keys representing the final name & the values acting as a lookup path.

If the lookup path has no periods (i.e. name) in it, it’s considered to be an attribute/key on the item being processed. If that item looks like a dict, key access is attempted. If it looks like an object, attribute access is used. In either case, the found value is returned.

If the lookup path has periods (i.e. entry.title), it is split on the periods (like a Python import path) and recursively uses the previous value to look up the next value until a final value is found.

Overriding `prepare`¶

For every item (object or dict) that gets serialized as output, it runs through a prepare method on your Resource subclass.

The default behavior checks to see if you have fields defined on your class & either just returns all the data (if there’s no fields) or uses the fields to extract plain data.

However, you can use/abuse this method for your own nefarious purposes. For example, if you wanted to serve an API of users but sanitize the data, you could do something like:

from django.contrib.auth.models import User

from restless.dj import DjangoResource
from restless.preparers import FieldsPreparer


class UserResource(DjangoResource):
    preparer = FieldsPreparer(fields={
        'id': 'id',
        'username': 'username',
        # We're including email here, but we'll sanitize it later.
        'email': 'email',
        'date_joined': 'date_joined',
    })

    def list(self):
        return User.objects.all()

    def detail(self, pk):
        return User.objects.get(pk=pk)

    def prepare(self, data):
        # ``data`` is the object/dict to be exposed.
        # We'll call ``super`` to prep the data, then we'll mask the email.
        prepped = super(UserResource, self).prepare(data)

        email = prepped['email']
        at_offset = email.index('@')
        prepped['email'] = email[:at_offset + 1] + "..."

        return prepped

This example is somewhat contrived, but you can perform any kind of transformation you want here, as long as you return a plain, serializable dict.

Per-Method Data¶

Because Restless can serve plain old Python objects (anything JSON serializable + datetime + decimal), the ultimate form of control is simply to load your data however you want, then return a simple/serializable form.

For example, Django’s models.Model classes are not normally JSON-serializable. We also may want to expose related data in a nested form. Here’s an example of doing something like that.:

from restless.dj import DjangoResource

from posts.models import Post


class PostResource(DjangoResource):
    def detail(self, pk):
        # We do our rich lookup here.
        post = Post.objects.get(pk=pk).select_related('user')

        # Then we can simplify it & include related information.
        return {
            'title': post.title,
            'author': {
                'id': post.user.id,
                'username': post.user.username,
                'date_joined': post.user.date_joined,
                # We exclude things like ``password`` & ``email`` here
                # intentionally.
            },
            'body': post.content,
            # ...
        }

While this is more verbose, it gives you all the control.

If you have resources for your nested data, you can also re-use them to make the construction easier. For example:

from django.contrib.auth.models import User

from restless.dj import DjangoResource
from restless.preparers import FieldsPreparer

from posts.models import Post


class UserResource(DjangoResource):
    preparer = FieldsPreparer(fields={
        'id': 'id',
        'username': 'username',
        'date_joined': 'date_joined',
    })

    def detail(self, pk):
        return User.objects.get(pk=pk)


class PostResource(DjangoResource):
    def detail(self, pk):
        # We do our rich lookup here.
        post = Post.objects.get(pk=pk).select_related('user')

        # Instantiate the ``UserResource``
        ur = UserResource()

        # Then populate the data.
        return {
            'title': post.title,
            # We leverage the ``prepare`` method from above to build the
            # nested data we want.
            'author': ur.prepare(post.user),
            'body': post.content,
            # ...
        }

Data Validation¶

Validation can be a contentious issue. No one wants to risk data corruption or security holes in their services. However, there’s no real standard or consensus on doing data validation even within the individual framework communities themselves, let alone between frameworks.

So unfortunately, Restless mostly ignores this issue, leaving you to do data validation the way you think is best.

The good news is that the data you’ll need to validate is already in a convenient-to-work-with dictionary called Resource.data (assigned immediately after deserialization takes place).

The recommended approach is to simply add on to your data methods themselves. For example, since Django Form objects are at least bundled with the framework, we’ll use those as an example...:

from django.forms import ModelForm

from restless.dj import DjangoResource
from restless.exceptions import BadRequest


class UserForm(ModelForm):
    class Meta(object):
        model = User
        fields = ['username', 'first_name', 'last_name', 'email']


class UserResource(DjangoResource):
    preparer = FieldsPreparer(fields={
        "id": "id",
        "username": "username",
        "first_name": "first_name",
        "last_name": "last_name",
        "email": "email",
    })

    def create(self):
        # We can create a bound form from the get-go.
        form = UserForm(self.data)

        if not form.is_valid():
            raise BadRequest('Something is wrong.')

        # Continue as normal, using the form data instead.
        user = User.objects.create(
            username=form.cleaned_data['username'],
            first_name=form.cleaned_data['first_name'],
            last_name=form.cleaned_data['last_name'],
            email=form.cleaned_data['email'],
        )
        return user

If you’re going to use this validation in other places, you’re welcome to DRY up your code into a validation method. An example of this might look like...:

from django.forms import ModelForm

from restless.dj import DjangoResource
from restless.exceptions import HttpError


class UserForm(ModelForm):
    class Meta(object):
        model = User
        fields = ['username', 'first_name', 'last_name', 'email']


class UserResource(DjangoResource):
    preparer = FieldsPreparer(fields={
        "id": "id",
        "username": "username",
        "first_name": "first_name",
        "last_name": "last_name",
        "email": "email",
    })

    def validate_user(self):
        form = UserForm(self.data)

        if not form.is_valid():
            raise BadRequest('Something is wrong.')

        return form.cleaned_data

    def create(self):
        cleaned = self.validate_user()
        user = User.objects.create(
            username=cleaned['username'],
            first_name=cleaned['first_name'],
            last_name=cleaned['last_name'],
            email=cleaned['email'],
        )
        return user

    def update(self, pk):
        cleaned = self.validate_user()
        user = User.objects.get(pk=pk)
        user.username = cleaned['username']
        user.first_name = cleaned['first_name']
        user.last_name = cleaned['last_name']
        user.email = cleaned['email']
        user.save()
        return user

Alternative Serialization¶

For some, Restless’ JSON-only syntax might not be appealing. Fortunately, overriding this is not terribly difficult.

For the purposes of demonstration, we’ll implement YAML in place of JSON. The process would be similar (but much more verbose) for XML (& brings a host of problems as well).

Start by creating a Serializer subclass for the YAML. We’ll override a couple methods there. This code can live anywhere, as long as it is importable for your Resource.:

import yaml

from restless.serializers import Serializer


class YAMLSerializer(Serializer):
    def deserialize(self, body):
        # Do **NOT** use ``yaml.load`` here, as it can contain things like
        # *functions* & other dangers!
        return yaml.safe_load(body)

    def serialize(self, data):
        return yaml.dump(data)

Once that class has been created, it’s just a matter of assigning an instance onto your Resource.:

# Old.
class MyResource(Resource):
    # This was present by default.
    serializer = JSONSerializer()

# New.
class MyResource(Resource):
    serializer = YAMLSerializer()

You can even do things like handle multiple serialization formats, say if the user provides a ?format=yaml GET param...:

from restless.serializers import Serializer
from restless.utils import json, MoreTypesJSONEncoder

from django.template import Context, Template


class MultiSerializer(Serializer):
    def deserialize(self, body):
        # This is Django-specific, but all frameworks can handle GET
        # parameters...
        ct = request.GET.get('format', 'json')

        if ct == 'yaml':
            return yaml.safe_load(body)
        else:
            return json.load(body)

    def serialize(self, data):
        # Again, Django-specific.
        ct = request.GET.get('format', 'json')

        if ct == 'yaml':
            return yaml.dump(body)
        else:
            return json.dumps(body, cls=MoreTypesJSONEncoder)

Extending Restless¶

Custom Endpoints¶

Customizing Data Output¶

Fields¶

Overriding `prepare`¶

Per-Method Data¶

Data Validation¶

Alternative Serialization¶

Table Of Contents

Previous topic

Next topic

This Page

Extending Restless¶

Custom Endpoints¶

Customizing Data Output¶

Fields¶

Overriding prepare¶

Per-Method Data¶

Data Validation¶

Alternative Serialization¶

Overriding `prepare`¶