image.png

注意：这是版本3的文档。还提供了版本2的文档。

image.png

Django REST framework 是一个强大且灵活的工具包，用以构建Web APIs。
为什么要使用REST framework？

• 在线可视的API，对于赢得你的开发者们十分有用
• 验证策略涵盖了OAuth1a和OAuth2
• 同时支持ORM和非ORM数据源的序列化
• 可以配置各个环节，若无需更多强大的特性，使用一般基于类（function-based）的视图（views）即可
• 大量的文档，强力的社区支持
• 大公司如同Mozilla和Eventbrite，也是忠实的使用者
  
  image.png

Funding（资金来源）

REST framework is a collaboratively(合作地) funded project(基金项目). If you use REST framework commercially（商业化的） we strongly（强烈） encourage（建议） you to invest(投资) in its continued development(可持续发展) by signing up for a paid plan.(注册付费计划)

Every single（每次简单） sign-up helps us make REST framework long-term financially（财政上） sustainable(财务上可持续发展)

Many thanks to all our wonderful sponsors(赞助商), and in particular to our premium backers(优质的支持者), Rover, Sentry, Stream, Machinalis, and Rollbar.
（非常感谢我们所有的优秀赞助商，特别是我们的优秀支持者， Rover, Sentry, Stream, Machinalis, and Rollbar.
）

image.png

配置要求（ Requirements）

REST framework 有以下的要求：

Python (2.7, 3.2, 3.3, 3.4, 3.5，3.6)
Django (1.7+, 1.8, 1.9，,2.0)

下面是可选的包：

• coreapi (1.32.0+) - 模式生成支持。
• Markdown (2.1.0+) - Markdown为可视化 API 提供了支持.
• django-filter (1.0.1+) - 过滤支持.
• django-crispy-forms - 为过滤，提供了改良的HTML呈现.
• django-guardian (1.1.1+) - 对象层面的权限支持.

安装 Installation

Install using pip, including any optional packages you want...（使用pip安装，包括任何你想要的可选包裹...）

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

...or clone the project from github.（或者从GitHub复制项目）

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

Add 'rest_framework' to your INSTALLED_APPS setting.

INSTALLED_APPS = (
    ...
    'rest_framework',
)

If you're intending to use the browsable API you'll probably also want to add REST framework's login and logout views. Add the following to your root urls.py file.（如果您打算使用可浏览的API，您可能还需要添加REST框架的登录和注销视图。将以下内容添加到您的根urls.py文件中。）

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

Note that the URL path can be whatever you want.（注意，url路径可以是任何你想要的。）

示例 Example

Let's take a look at a quick example of using REST framework to build a simple model-backed API.让我们来看看一个使用REST framework构建一个简单模型支持api的快速示例。

We'll create a read-write API for accessing information on the users of our project.（我们将创建一个读写api，用于访问项目用户的信息。）

Any global settings for a REST framework API are kept in a single configuration dictionary named REST_FRAMEWORK. Start off by adding the following to your settings.py module:（REST framework api的任何全局设置都保存在一个名为“rest_wramework”的配置词典中。首先在“环境”模块中添加以下内容：）

REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
    ]
}

Don't forget to make sure you've also added rest_framework to your INSTALLED_APPS.（别忘了确保你已经在“INSTALLED_APPS”中添加了“rest_framework”。）

We're ready to create our API now. Here's our project's root urls.py module:（我们准备好创建我们的api了。这是我们项目的根源 urls.py模块：）

from django.conf.urls import url, include
from django.contrib.auth.models import User
from rest_framework import routers, serializers, viewsets

# Serializers define the API representation.
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ('url', 'username', 'email', 'is_staff')

# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

# Routers provide an easy way of automatically determining the URL conf.
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)

# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
    url(r'^', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

You can now open the API in your browser at http://127.0.0.1:8000/, and view your new 'users' API. If you use the login control in the top right corner you'll also be able to add, create and delete users from the system.（现在，您可以在浏览器中输入‘http://127.0.0.1:8000/’打开api，并查看您的新“用户”api。如果您使用右上角的登录控件，您也可以从系统中添加、创建和删除用户。）

快速启动 Quickstart

Can't wait to get started? The quickstart guide is the fastest way to get up and running, and building APIs with REST framework.（等不及要开始了？快速启动指南是最快的建立和运行的方式，并建立REST framework的apis。）

教程 Tutorial

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.（本教程将帮助您完成组成REST框架的构建块。这需要一点时间来完成，但是它会给你一个全面的理解如何把一切结合起来，并强烈推荐阅读。）

• 1 - Serialization序列化

• 2 - Requests & Responses请求与相应

• 3 - Class-based views基于类的视图

• 4 - Authentication & permissions认证与权限

• 5 - Relationships & hyperlinked APIs关系与超链接型API

• 6 - Viewsets & routers视图组与路由

• 7 - Schemas & client libraries模式与客户端库

There is a live example API of the finished tutorial API for testing purposes, available here.这里有一个用于测试目的的完成教程API的实例化API，这里可获得

API指南 API Guide

The API guide is your complete reference manual to all the functionality provided by REST framework.（API指南是您对REST框架提供的所有功能的完整参考手册）

• Requests请求
• Responses响应
• Views视图
• Generic views通用视图
• Viewsets视图集
• Routers路由器
• Parsers解析器
• Renderers渲染器
• Serializers序列化
• Serializer fields序列化字段
• Serializer relations序列化器的关系
• Validators验证器
• Authentication认证
• Permissions权限
• Throttling节流
• Filtering过滤
• Pagination分页
• Versioning版本控制
• Content negotiation内容协商
• Metadata元数据
• Schemas模式
• Format suffixes格式后缀
• Returning URLs返回的url
• Exceptions异常
• Status codes状态码
• Testing测试
• Settings设置

论题Topics

General guides to using REST framework.（使用REST框架的一般指南。）

• Documenting your API记录你的api
• API ClientsAPI客户端
• Internationalization国际化
• AJAX, CSRF & CORS
• HTML & Forms
• Browser enhancements浏览器增强
• The Browsable API可浏览的API
• REST, Hypermedia & HATEOASREST，超媒体和HATOOAS
• Third Party Packages第三方软件包
• Tutorials and Resources教程和资源
• Contributing to REST framework有助于REST框架
• Project management项目管理
• 3.0 Announcement公告
• 3.1 Announcement
• 3.2 Announcement
• 3.3 Announcement
• 3.4 Announcement
• 3.5 Announcement
• 3.6 Announcement
• 3.7 Announcement
• 3.8 Announcement
• Kickstarter Announcement
• Mozilla Grant
• Funding
• Release Notes
• Jobs

发展 Development

See the Contribution guidelines for information on how to clone the repository, run the test suite and contribute changes back to REST Framework.（有关如何克隆存储库、运行测试套件以及向REST框架贡献更改的信息，请参阅贡献指南。）

支持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.（要获得支持，请参阅REST框架讨论组，在IRC .freenode.net上尝试#restframework通道，搜索IRC档案，或者对Stack Overflow提出问题，确保包含“django-rest-framework”标签。）

For priority support please sign up for a professional or premium sponsorship plan.（如需优先支持，请注册专业或优质赞助计划。）

For updates on REST framework development, you may also want to follow the author on Twitter.（对于REST框架开发的更新，您可能还希望在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-2017, 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.