Django REST framework

Django REST framework(翻译的官方工具书)

神奇的浏览器APIs.

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, include
from 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 ​​#restframework​​channel 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 Twitter.

​​Follow @_tomchristie​​

Security

If you believe you’ve found something in Django REST framework which has security implications, please do not raise the issue in a public forum.

Send a description of the issue via email to ​​rest-framework-security@googlegroups.com​​. The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure.

License

Copyright (c) 2011-2013, Tom Christie All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.