URL Routing

Standard route

To add a new API route, you must create a new class inheriting from rest_api.API.API:

from rest_api.API import API

class ProjectAPI(API):
    pass

After this, you must register this API in order to 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 matches the following urls based on the above pattern:

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, retrieved automatically in the name of your class (here "ProjectAPI", so this is "project").

Now, you must create one method for each route and for each HTTP method request, using 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 sent 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, you will want to add a custom route. To achieve 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, you could do:

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 that we have seen previously (which are list and detail by default). You can also easily add a new variable in the url, with a regex, and a name for this (in example, _id2). This variable is also send to the corresponding methods.