django-api

RESTful API Library for Django Projects

Assumptions

This library makes some assumptions about your project:

1. Controller class names match the model class name they are wrapping
2. Controller class names use upper camel case (for example PostCache)
3. Any foreign keys use the underscore case equivalent of the model class name they point to (for example post_cache)
4. All URLs and returned results will use underscore case, which will then be converted to camel case automatically

Getting Started

pip install django-mint

Let's assume we're using the following database schema:

# myapp/models.py
from django.db import models
from django.contrib.auth.models import User

class Post(models.Model):
  name = models.TextField()
  contributors = models.ManyToManyField(User)

class PostCache(models.Model):
  post = models.ForeignKey(Post)
  data = models.TextField()

Create your the controllers for these models (usually in a file called controllers.py)

# web/controllers.py
from mint.controller import Controller
from myapp import models

class PostCache(Controller):
  model = models.PostCache

class Post(Controller):
  model = models.Post
  related = [PostCache]

Create a file called rest.py somewhere and put the following code in it:

# web/rest.py
from mint.coordinator import Coordinator
from web import controllers

class RESTCoordinator(Coordinator):
  controllers = (
    controllers.Post
  )

Add the following to your settings.py

REST_COORDINATOR_PATH = 'web.rest.RESTCoordinator'  # Full dotted path to the class we just made

Finally, in your urls.py add:

url(r'^api/1', include('api.urls')),

You now have a fully functioning REST API with full CRUD operations.

All API calls will have a key called result which will be either true or false, depending on whether the call succeeded or not. If the call did not succeed there will be a key called error with the name of the exception, and a key called message with a descriptive message of what went wrong. Also if DEBUG is True there will be a key called trackback with the full stack trace.

For example the following will work:

GET /api/1/post #  Returns a list of all posts in a key called `posts`
POST /api/1/post #  Pass either form parameters or json to create a new post. The newly created post will be returned in a key called `post`
GET /api/1/post/1 #  Returns a post with that ID in a key called `post`, or a 404 if not found
PUT /api/1/post/1 #  Pass either form parameters or json to update post with that ID. The updated post will be returned in a key called `post`
DELETE /api/1/post/1 #  Deletes a post with that ID, or returns a 404 if not found.
GET /api/1/post/1/post_cache #  Returns all PostCaches that are related to a post with that ID in a key called `post_caches`.
POST /api/1/post/1/contributors #  Create a new contributor to be associated with the post. The new contributor is returned in a key called `contributor`.