django-api
RESTful API Library for Django Projects
Assumptions
This library makes some assumptions about your project:
- Controller class names match the model class name they are wrapping
- Controller class names use upper camel case (for example PostCache)
- Any foreign keys use the underscore case equivalent of the model class name they point to (for example post_cache)
- 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`.