Django REST framework

Django REST 框架可以轻松部署web APIs，其是一个聚健壮性与弹性于一体的web工具包。

以下所列可以作为选择其的理由:

• Web browseable API对于开发者来说足以胜任web开发.
• Authentication policies 内包括 OAuth1a 和OAuth2 .
•  ORM 和 non-ORM 数据源都支持序列化.
• 如果你不要使用更强力的工具只需使用 regular function-based views .
• 深度讲解的文档和多角度的社区支持.

下面是生动的web实例.

Below: Screenshot from the browsable API

要求：

REST 需要以下部件:

• Python (2.6.5+, 2.7, 3.2, 3.3)
• Django (1.3, 1.4, 1.5, 1.6)

如下是可选组件:

• Markdown (2.1.0+) - Markdown support for the browsable API.
• PyYAML (3.10+) - YAML content-type support.
• defusedxml (0.3+) - XML content-type support.
• django-filter (0.5.4+) - Filtering support.
• django-oauth-plus (2.0+) and oauth2 (1.5.211+) - OAuth 1.0a support.
• django-oauth2-provider (0.2.3+) - OAuth 2.0 support.
• django-guardian (1.1.1+) - Object level permissions support.

注意: The oauth2 Python package is badly misnamed, and actually provides OAuth 1.0a support. Also note that packages required for both OAuth 1.0a, and OAuth 2.0 are not yet Python 3 compatible.

安装

使用 pip, 其内包涵很多部件...

pip install djangorestframework  pip install markdown       # Markdown support for the browsable API. pip install django-filter  # Filtering support

...或者可以从github chone.

git clone git@github.com:tomchristie/django-rest-framework.git

将 'rest_framework' 添加到 INSTALLED_APPS setting中.

INSTALLED_APPS = (     ...     'rest_framework',        )

如果你想要使用web浏览器APIs并且想添加REST 框架的登出与登录视图. 将下面的code添加到 urls.py 文件中.

urlpatterns = patterns('',     ...     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) )

注意：URL 路径可以放在任何地方, 但是你必须把'rest_framework.urls' 包涵在 'rest_framework' 中.

列子：

迅速的看一下 用REST 框架 搭建的一个简单的模块APIs.

我们将创建一个提供读写users和groups的API .

任何设置为 REST框架的 API 都被放入一个named REST_FRAMEWORK的文件中. 然后把其添加到 settings.py module中:

REST_FRAMEWORK = {     # Use hyperlinked styles by default.     # Only used if the `serializer_class` attribute is not set on a view.     'DEFAULT_MODEL_SERIALIZER_CLASS':         'rest_framework.serializers.HyperlinkedModelSerializer',     # Use Django's standard `django.contrib.auth` permissions,     # or allow read-only access for unauthenticated users.     'DEFAULT_PERMISSION_CLASSES': [         'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'     ] }

不要忘记把 rest_framework 添加到 INSTALLED_APPS.

如今已经为创建 API 做好准备. 如下是工程的 跟urls.py 模块:

from django.conf.urls.defaults import url, patterns, includefrom django.contrib.auth.models import User, Group from rest_framework import viewsets, routers# ViewSets define the view behavior. class UserViewSet(viewsets.ModelViewSet):     model = User class GroupViewSet(viewsets.ModelViewSet):     model = Group # Routers provide an easy way of automatically determining the URL conf router = routers.DefaultRouter() router.register(r'users', UserViewSet) router.register(r'groups', GroupViewSet) # Wire up our API using automatic URL routing. # Additionally, we include login URLs for the browseable API. urlpatterns = patterns('',     url(r'^', include(router.urls)),     url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) )

快速开始

等不及开始了？ 快速导航是一个简易的步骤, 并可以创建REST框架的 APIs.

指南书：

The tutorial will walk you through the building blocks that make up REST framework. It'll take a little while to get through, but it'll give you a comprehensive understanding of how everything fits together, and is highly recommended reading.

• 1 - Serialization
• 2 - Requests & Responses
• 3 - Class based views
• 4 - Authentication & permissions
• 5 - Relationships & hyperlinked APIs
• 6 - Viewsets & routers

API Guide

The API guide is your complete reference manual to all the functionality provided by REST framework.

• Requests
• Responses
• Views
• Generic views
• Viewsets
• Routers
• Parsers
• Renderers
• Serializers
• Serializer fields
• Serializer relations
• Authentication
• Permissions
• Throttling
• Filtering
• Pagination
• Content negotiation
• Format suffixes
• Returning URLs
• Exceptions
• Status codes
• Testing
• Settings

主题：

REST 使用指南.

• Documenting your API
• AJAX, CSRF & CORS
• Browser enhancements
• The Browsable API
• REST, Hypermedia & HATEOAS
• 2.0 Announcement
• 2.2 Announcement
• 2.3 Announcement
• Release Notes
• Credits

Development

If you want to work on REST framework itself, clone the repository, then...

Build the docs:

./mkdocs.py

Run the tests:

./rest_framework/runtests/runtests.py

To run the tests against all supported configurations, first install the tox testing tool globally, using pip install tox, then simply run tox:

tox

Support

For support please see the REST framework discussion group, try the #restframeworkchannel on irc.freenode.net, search the IRC archives, or raise a question on Stack Overflow, making sure to include the 'django-rest-framework' tag.

Paid support is available from DabApps, and can include work on REST framework core, or support with building your REST framework API. Please contact DabApps if you'd like to discuss commercial support options.

For updates on REST framework development, you may also want to follow the author on 推ter.