jaad 0.11

An additional layer to Django aiming to simplify resilient API creation

Jaad

Overview

Jaad is an addition to Django.

It is based on Django Rest Framework and is designed to simplify the syntax needed to expose a resilient REST API.

Installation

To install Jaad using pip run:

pip install jaad

Creating a new project

To create a new project create a project directory and use jaad-admin.py startproject.

This will create the following files:

.
|-- server/
|     |-- apps/
|     |    |-- __init__.py
|     |    `-- index/
|     |         |-- __init__.py
|     |         |-- parameters.py
|     |         `-- view.py
|     |-- logs/
|     |-- settings/
|     |    |-- __init__.py
|     |    |-- application.py
|     |    |-- local.py
|     |    `-- __init__.py
|     `-- urls.py
`-- manage.py

manage.py is the classic Django management script hence you can run your server using:

DJANGO_SETTINGS_MODULE=server.settings.local python manage.py runserver

This will launch your server and make it available here: http://127.0.0.1:8000/

A default Index view was automatically created.

You can have a look at its definition in server/apps/index/ as it uses Jaad core features.

Creating a new view

To create a view create a submodule in apps and define in it a class inheriting from JaadView. Then define the HTTP method you want to support:

from jaad.view import JaadView

class Hello(JaadView):
    def get(self, request):
        return "Hello"

    def post(self, request):
        return "This was a POST request"

You can then expose it by modifying server/urls.py

Defining parameters

You can define a set of parameters that a view support using a Jaad Form:

from jaad.forms import fields


class HelloWorldParameters(fields.Form):
    name = fields.StringField(
        required=True,
        help_text="Enter your name :)"
    )

And then using it in your views:

from jaad.view import JaadView, with_parameters


class Hello(JaadView):
    @with_parameters("GET", HelloWorldParameters)
    def get(self, request, parameters):
        return "Hello {}".format(parameters["name"])

    def post(self, request):
        return "This was a POST request"

The additional parameter used to call your method contains your parameter values validated and converted to python objects (int, datetime, ...).

with_parameters can be called with as many Form as you want and will add a parameter to your method for each Form.

Interactive documentation

You can add an interactive documentation to your API using jaad-admin.py add-doc.

This will create the following files in server/apps/

documentation/
    |-- static/
    |     `-- css/
    |          `-- documentation.css
    |-- templates/
    |     `-- rest_framework_swagger/
    |          |-- base.html
    |          `-- index.html
    `-- urls.py

This is a Swagger UI that relies on Django Rest Framework Swagger and is not exposed yet.

To expose it:

1. In server/urls.py import include from django.conf.urls if not already done and add url(r'^doc/', include('documentation.urls')) to urlpatterns.
2. Add 'server.apps.documentation' to INSTALLED_APPS in server/settings/application.py

You can now access your API documentation on http://127.0.0.1:8000/doc/

The documentation is automatically updated based on all exposed view docstrings and parameter definitions.