Simple Routing

Combinating the power of Django and the resources it’s relatively easy to buid an api. The process is also eased using the WM object. dj-webmachine offer a way to create automatically resources by using the route decorator.

Using this decorator, our helloworld example can be rewritten like that:

from webmachine.ap import wm

import json
@wm.route(r"^$")
def hello(req, resp):
    return "<html><p>hello world!</p></html>"


@wm.route(r"^$", provided=[("application/json", json.dumps)])
def hello_json(req, resp):
    return {"ok": True, "message": "hellow world"}

and the urls.py:

from django.conf.urls.defaults import *

import webmachine

webmachine.autodiscover()

urlpatterns = patterns('',
    (r'^', include(webmachine.wm.urls))
)

The autodiscover will detect all resources modules and add then to the url dispatching. The route decorator works a little like the one in bottle or for that matter flask (though bottle was the first).

This decorator works differently though. It creates full webmachine.resource.Resource instancse registered in the wm object. So we are abble to provide all the features available in a resource:

  • settings which content is accepted, provided
  • assiciate serializers to the content types
  • throttling
  • authorization

The helloworld could be written in one function:

def resource_exists(req, resp):
    return True

@wm.route(r"^hello$",
        provided=["text/html", ("application/json", json.dumps)],
        resource_exists=resource_exists

        )
def all_in_one(req, resp):
    if resp.content_type == "application/json":
        return {"ok": True, "message": "hellow world! All in one"}
    else:
        return "<html><p>hello world! All in one</p></html>"

You can see that we set in the decorator the provided contents, we call a function resources_exists to check if this resource exists. Then in the function we return the content dependiong on the response content type depending on the HTTP requests. The response is then automatically serialized using the json.dumps function associated to the json content-type. Easy isn’t it ? You can pass any resource methods to the decorator.

Mapping a resource

You can also map your Resources classes using the wm object and the method webmachine.api.WM.add_resource()

If a pattern is given, the path will be /<wmpath>/<app_label>/pattern/resource urls. if no pattern is given the resource_name will be used.

Ex for urls.py:

from django.conf.urls.defaults import *

import webmachine
webmachine.autodiscover()

urlpatterns = patterns('',
    (r'^wm/', include(webmachine.wm.urls)),

)

and a resources.py file in one django app named hello

from webmachine import Resource
from webmachine import wm

class Hello(Resource):

    def to_html(self, req, resp):
        return "<html><body>Hello world!</body></html>\n"


# available at wm/hello
wm.add_resource(Hello, r"^hello")

# available at wm/helloworld/hello
wm.add_resource(Hello)

You can then access to /wm/hello and /wm/hello/hello pathes automatically.

You can also override the resource path by using the Meta class:

class Hello(Resource):
    class Meta:
        resource_path = ""

If you set the resource path, the resource url added to the WM instance i /<wmpath>/<app_label>/<resource_path>/resource_urls .

Custom WM instance

Sometimes you want to create custom WM instance instead to use the global one provided. For that you can import the class webmachine.api.WM:

class webmachine.api.WM(name='webmachine', version=None)[source]
add_resource(klass, pattern=None)[source]

add one Resource class to the routing.

Attr klass:class inheriting from :class:webmachine.Resource
Attr pattern:regexp.
add_resources(*klasses)[source]

allows you to add multiple Resource classes to the WM instance. You can also pass a pattern by using a tupple instead of simply provided the Resource class. Ex:

(MyResource, r"^some/path$")
add_route(pattern, func, **kwargs)[source]
get_urls()[source]
route(pattern, **kwargs)[source]

A decorator that is used to register a new resource using this function to return response.

Parameters

Attr pattern:regular expression, like the one you give in

your urls.py

Attr methods:methods accepted on this function
Attr provides:list of provided contents tpes and associated

serializers:

[(MediaType, Handler)]
Attr accepted:list of content you accept in POST/PUT with

associated deserializers:

[(MediaType, Handler)]

A serializer can be a simple callable taking a value or a class:

class Myserializer(object):

    def unserialize(self, value):
        # ... do something to value
        return value

    def serialize(self, value):
        # ... do something to value
        return value
Attr formats:return a list of format with their associated

contenttype:

[(Suffix, MediaType)]
Attr kwargs:any named parameter coresponding to a

resource method. Each value is a callable taking a request and a response as arguments:

def f(req, resp):
    pass
urls

Table Of Contents

Previous topic

dj-webmachine Resource object methods

Next topic

Handle authorization

This Page