Bambu API¶
Quickly expose your models to a JSON or XML API, authenticated via HTTP or OAuth.
About Bambu API¶
This package allows you to easily expose Django models to RESTful endpoints which can send data in XML or JSON format.
About Bambu Tools 2.0¶
This is part of a toolset called Bambu Tools. It’s being moved from a
namespace of bambu to its own ‘root-level’ package, along with all
the other tools in the set. If you’re upgrading from a version prior to
2.0, please make sure to update your code to use bambu_api rather
than bambu.api.
Installation¶
Install the package via Pip:
pip install bambu-api
Add it to your INSTALLED_APPS list:
INSTALLED_APPS = (
...
'bambu_api'
)
Add bambu_api.urls to your URLconf:
urlpatterns = patterns('',
...
url(r'^', include('bambu_api.urls')),
)
The prefix should be kept blank, as the package exposes two main URL
stems: /api/, wherein the RESTful endpoints live, and /docs/
where auto-generated documentation for each endpoint is found.
Basic usage¶
You define API endpoints like Django admins, and register them in a similar way.
Teka the Django ‘polls’ app as an example. Within the polls directory, you’d create a file called api.py. A simple API endpoint would be defined like this:
from bambu_api import ModelAPI, site
from myproject.polls.models import Question
class QuestionAPI(ModelAPI):
pass
site.register(Question, QuestionAPI)
This registers the QuestionAPI endpoint for the Question model.
The endpoint is then accessible at /api/polls/question.json.
Questions or suggestions?¶
Find me on Twitter (@iamsteadman) or visit my blog.
Contents¶
Defining and registering endpoints¶
Settings¶
API_AUTH_BACKEND- The provider used to authenticate users through the API (default is ‘bambu_api.auth.http.HTTPAuthentication’)
API_AUTH_REALM- The HTTP authentication realm (default is ‘Restricted access’)
API_LOGIN_URL- The URL to redirect anonymous API users to (defaults to the result of reversing the URL name ‘login’)
API_AUTH_ALLOW_REGISTRATION- When
True, this allows users to sign up via the API thus creating anauth.Userobject (defaults toFalse) API_ALLOW_USER_MANAGEMENT- When
True, allows users to edit their login details via the API (defaults toFalse) API_ALLOW_GROUP_MANAGEMENT- When
True, allows authenticated users to create, read, update and deleteauth.Groupobjects (defaults toFalse) API_CACHE_VARY_HEADERS- Which HTTP headers are used to decide whether to cache content or not. Defaults to ‘Cookie’
API_THROTTLE_REQUESTS- The number of requests permitted in X minutes (where X is the value of
API_THROTTLE_MINUTES). The default is 60. API_THROTTLE_MINUTES- The number of minutes that defines how many requests to allow before throttling. The default is 1.
API_REQUEST_LOGGER- The default request logger to use (the means by which throttling occurs). Specify the fully qualified module and class name of the logger. Defaults to ‘bambu_api.requestlogging.DatabaseRequestLogger’
Redis-specific settings¶
If using Redis to log the number of requests by a specific app for throttling, you can configure Bambu API to use a specific host and database
API_REDIS_HOST- The Redis host to use (defaults to ‘localhost’)
API_REDIS_PORT- The Redis port to use (defaults to 6379)
API_REDIS_DB- The index of the Redis database to use (defaults to 0)
API_REDIS_PASSWORD- The password for the Redis database (defaults to ‘’)