Welcome to Tastypie!¶
Tastypie is a 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
- Python 3 Support
- Resources
- Bundles
- Api
- Resource Fields
- Caching
- Validation
- Authentication
- Authorization
- Serialization
- Throttling
- Paginator
- GeoDjango
- ContentTypes and GenericForeignKeys
- Namespaces
- Tastypie Cookbook
- Debugging Tastypie
- Sites Using Tastypie
- Contributing
Quick Start¶
Add
tastypie
toINSTALLED_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 django.conf.urls import url, include from tastypie.api import Api from my_app.api.resources import MyModelResource v1_api = Api(api_name='v1') v1_api.register(MyModelResource()) urlpatterns = [ # ...more URLconf bits here... # Then add: url(r'^api/', include(v1_api.urls)), ]
Hit http://localhost:8000/api/v1/?format=json in your browser!
Requirements¶
Core¶
- Python 2.7+ or Python 3.4+
- Django 1.8 or 1.11 (LTS releases)
- dateutil (http://labix.org/python-dateutil) >= 2.1
Format Support¶
- XML: lxml 3 (http://lxml.de/) and defusedxml (https://pypi.python.org/pypi/defusedxml)
- YAML: pyyaml (http://pyyaml.org/)
- binary plist: biplist (http://explorapp.com/biplist/)
Optional¶
- HTTP Digest authentication: python3-digest (https://bitbucket.org/akoha/python-digest/)
Why Tastypie?¶
There are other 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).
Reference Material¶
- https://django-tastypie.readthedocs.io/en/latest/
- https://github.com/django-tastypie/django-tastypie/tree/master/tests/basic shows basic usage of tastypie
- http://en.wikipedia.org/wiki/REST
- http://en.wikipedia.org/wiki/List_of_HTTP_status_codes
- http://www.ietf.org/rfc/rfc2616.txt
- http://jacobian.org/writing/rest-worst-practices/
Getting Help¶
There are two primary ways of getting help.
- Go to StackOverflow and post a question with the
tastypie
tag. - We have an IRC channel (#tastypie on irc.freenode.net) to get help, bounce an idea by us, or generally shoot the breeze.
Running The Tests¶
The easiest way to get setup to run Tastypie’s tests looks like:
$ git clone https://github.com/django-tastypie/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
$ ./env/bin/pip install tox
$ tox
Tastypie is maintained with all tests passing at all times for released
dependencies. (At times tests may fail with development versions of Django.
These will be noted as allowed failures in the .travis.yml
file.) If you
find a failure, please report it along with the versions of the installed
software.