An additional layer to Django aiming to simplify resilient API creation
Project description
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:
- In
server/urls.py
importinclude
fromdjango.conf.urls
if not already done and addurl(r'^doc/', include('documentation.urls'))
to urlpatterns. - Add
'server.apps.documentation'
toINSTALLED_APPS
inserver/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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.