Welcome to Tastypie!¶
Tastypie is an webservice API framework for Django. It provides a convenient, yet powerful and highly customizable, abstraction for creating REST-style interfaces.
- Getting Started with Tastypie
- Interacting With The API
- Tastypie Settings
- Using Tastypie With Non-ORM Data Sources
- Tools
- Testing
- Compatibility Notes
- Resources
- Quick Start
- Why Class-Based?
- Why Resource vs. ModelResource?
- Flow Through The Request/Response Cycle
- Why Resource URIs?
- Accessing The Current Request
- Advanced Data Preparation
- Reverse “Relationships”
- Resource Options (AKA Meta)
- Basic Filtering
- Advanced Filtering
- Using PUT/DELETE/PATCH In Unsupported Places
- Resource Methods
- ModelResource Methods
- Bundles
- Api
- Resource Fields
- Caching
- Validation
- Authentication
- Authorization
- Serialization
- Throttling
- Paginator
- GeoDjango
- ContentTypes and GenericForeignKeys
- Tastypie Cookbook
- Creating a Full OAuth 2.0 API
- Adding Custom Values
- Per-Request Alterations To The Queryset
- Using Your Resource In Regular Views
- Using Non-PK Data For Your URLs
- Nested Resources
- Adding Search Functionality
- Creating per-user resources
- camelCase JSON Serialization
- Pretty-printed JSON Serialization
- Determining format via URL
- Adding to the Django Admin
- Using SessionAuthentication
- Debugging Tastypie
- Sites Using Tastypie
- Contributing
- Release Notes
Getting Help¶
There are two primary ways of getting help. We have a mailing list hosted at Google (http://groups.google.com/group/django-tastypie/) and an IRC channel (#tastypie on irc.freenode.net) to get help, want to bounce idea or generally shoot the breeze.
Quick Start¶
Add tastypie to INSTALLED_APPS.
Create an api directory in your app with a bare __init__.py.
Create an <my_app>/api/resources.py file and place the following in it:
from tastypie.resources import ModelResource from my_app.models import MyModel class MyModelResource(ModelResource): class Meta: queryset = MyModel.objects.all() allowed_methods = ['get']
In your root URLconf, add the following code (around where the admin code might be):
from tastypie.api import Api from my_app.api.resources import MyModelResource v1_api = Api(api_name='v1') v1_api.register(MyModelResource()) urlpatterns = patterns('', # ...more URLconf bits here... # Then add: (r'^api/', include(v1_api.urls)), )
Hit http://localhost:8000/api/v1/?format=json in your browser!
Requirements¶
Tastypie requires the following modules. If you use Pip, you can install the necessary bits via the included requirements.txt:
Required¶
- Python 2.6+
- Django 1.3+
- mimeparse 0.1.3+ (http://code.google.com/p/mimeparse/)
- Older versions will work, but their behavior on JSON/JSONP is a touch wonky.
- dateutil (http://labix.org/python-dateutil) >= 1.5, < 2.0
Optional¶
- python_digest (https://bitbucket.org/akoha/python-digest/)
- lxml (http://lxml.de/) and defusedxml (https://bitbucket.org/tiran/defusedxml) if using the XML serializer
- pyyaml (http://pyyaml.org/) if using the YAML serializer
- biplist (http://explorapp.com/biplist/) if using the binary plist serializer
Why Tastypie?¶
There are other, better known API frameworks out there for Django. You need to assess the options available and decide for yourself. That said, here are some common reasons for tastypie.
- You need an API that is RESTful and uses HTTP well.
- You want to support deep relations.
- You DON’T want to have to write your own serializer to make the output right.
- You want an API framework that has little magic, very flexible and maps well to the problem domain.
- You want/need XML serialization that is treated equally to JSON (and YAML is there too).
- You want to support my perceived NIH syndrome, which is less about NIH and more about trying to help out friends/coworkers.
Reference Material¶
Running The Tests¶
The easiest way to get setup to run Tastypie’s tests looks like:
$ git clone https://github.com/toastdriven/django-tastypie.git
$ cd django-tastypie
$ virtualenv env
$ . env/bin/activate
$ ./env/bin/pip install -U -r requirements.txt
Then running the tests is as simple as:
# From the same directory as above:
$ ./env/bin/pip install -U -r tests/requirements.txt
$ cd tests
$ ./run_all_test.sh
Tastypie is maintained with all tests passing at all times. If you find a failure, please report it along with the versions of the installed software.
Commercial Support¶
If you’re using Tastypie in a commercial environment, paid support is available from Toast Driven. Services offered include:
- Advice/help with setup
- Implementation in your project
- Bugfixes in Tastypie itself
- Features in Tastypie itself
If you’re interested, please contact Daniel Lindsley (daniel@toastdriven.com).