URL Routing

Standard route

For add a new API route, you must create a new class herited from rest_api.API.API:

from rest_api.API import API

class ProjectAPI(API):
    pass

After this, you must register this API for use the routing of Django:

# -*- coding: utf-8 -*-
from django.conf.urls import patterns, url, include
from rest_api.register import RegisterAPI
from example.api_v1.project import ProjectAPI

api_v1 = RegisterAPI("1.0")  # Version of your API
api_v1.register(ProjectAPI())  # /api/1.0/project

urlpatterns = patterns(
    'example',
    url(r'^api/', include(api_v1.urls))
)

At this point, Django listen in:

Type list: /api/<version_api>/<name_api>
Type detail: /api/<version_api>/<name_api>/<id>

• version_api: Name or version of your API, this is the parameter of RegisterAPI.
• name_api: Name of the API, retrieve automatically in function of the name of your class (here "ProjectAPI", so this is "project").

After, you must create one method by route and method request, in this format:

method_<method>_<type>

• method: get, post, delete, and put are allowed.
• type: Type seen previously (list or detail). For the type detail, the id is send in parameter (called _id).

For example:

from rest_api.API import API

class ProjectAPI(API):
    # GET /api/1.0/project
    def method_get_list(self, session, request, **kwargs):
        # ...

    # GET /api/1.0/project/<id>
    def method_get_detail(self, session, request, _id, **kwargs):
        # ...

    # POST /api/1.0/project
    def method_post_list(self, session, request, **kwargs):
        # ...

    # PUT /api/1.0/project/<id>
    def method_put_detail(self, session, request, _id, **kwargs):
        # ...

    # DELETE /api/1.0/project/<id>
    def method_delete_detail(self, session, request, _id, **kwargs):
        # ...

Add custom route

Sometimes, we need to add a custom route. For this, you must override the method prepend_urls (don't forget to call the parent method).

For example, if you want manage the contributors of projects, we could done:

from rest_api.API import API
from django.conf.urls import url

class ProjectAPI(API):

    # ...

    def prepend_urls(self):
        urls = super().prepend_urls()
        urls.append(url(r"^%s/(?P<_id>[0-9]+)/contributors(/?)$" % self.resource_name,
                        self.dispatch_api("contributors_list")))
        urls.append(url(r"^%s/(?P<_id>[0-9]+)/contributors/(?P<_id2>[0-9]+)(/?)$" % self.resource_name,
                        self.dispatch_api("contributors_detail")))
        return urls

    # GET /api/1.0/project/<id>/contributors
    def method_get_contributors_list(self, session, request, _id, **kwargs):
        # ...

    # POST /api/1.0/project/<id>/contributors
    def method_post_contributors_list(self, session, request, _id, **kwargs):
        # ...

    # DELETE /api/1.0/project/<id>/contributors/<id>
    def method_delete_contributors_detail(self, session, request, _id, _id2, **kwargs):
        # ...

The parameter of the method dispatch_api is the type seen previously (which are list and detail by default). You can also easily add new variable in the url, with a regex, and a name for this (in example, _id2). This variable is so send to the corresponding methods.