Django REST Framework

Django REST framework 是用于构建 Web API 的强大而灵活的工具包。

您可能希望使用 REST framework 的一些原因：

Web 可浏览 API 对于开发人员来说是一个巨大的可用性胜利。
身份验证策略包括 OAuth1a 和 OAuth2 的程序包。
支持 ORM 和非 ORM 数据源的序列化。
一路可自定义下去 - 如果你不需要更强大的功能，只要使用正规的基于函数的视图。
丰富的文档和良好的社区支持。
受到国际知名公司的使用和信任，包括 Mozilla，Red Hat，Heroku 和 Eventbrite。

资金 (Funding)

REST framework 是一个由合作资助的项目。如果您在商业上使用 REST framework，我们强烈建议您通过注册付费计划来投资其持续开发。

每一次注册都有助于我们使 REST framework 在财务上具有长期可持续性。

非常感谢我们所有出色的赞助商，特别是我们的高级支持者，Rover，Sentry，Stream，Auklet，Rollbar，Cadre，Load Impact 和 Kloudless。

要求 (Requirements)

REST framework 需要以下内容：

Python (2.7, 3.4, 3.5, 3.6, 3.7)
Django (1.11, 2.0, 2.1)

以下包是可选的：

coreapi (1.32.0+) - 模式生成支持。
Markdown (2.1.0+) - 对可浏览 API 的 Markdown 支持。
django-filter (1.0.1+) - 过滤支持。
django-crispy-forms - 改进的 HTML 过滤显式。
django-guardian (1.1.1+) - 对象级权限支持。

安装 (Installation)

使用 pip 安装，包括您想要的任何可选包…

pip install djangorestframework
pip install markdown       # 对可浏览 API 的 Markdown 支持。
pip install django-filter  # 过滤支持

…或者从 github 克隆项目。

git clone [email protected].com:encode/django-rest-framework.git

将 'rest_framework' 添加到 INSTALLED_APPS 设置中。

INSTALLED_APPS = (
    ...
    'rest_framework',
)

如果您打算使用可浏览的 API，您可能还需要添加 REST framework 的登录和注销视图。将以下内容添加到根 urls.py 文件中。

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

请注意，URL路径可以是您想要的任何内容。

示例 (Example)

让我们来看一个使用 REST framework 来构建简单的模型支持的 API 的快速例子。

我们将创建一个读写 API 来访问关于项目用户的信息。

REST framework API 的任何全局设置都保存在名为 REST_FRAMEWORK 的单个配置字典中。首先将以下内容添加到 settings.py 模块：

REST_FRAMEWORK = {
    # 使用 Django 的标准 `django.contrib.auth` 权限，
    # 或允许未经身份验证的用户进行只读访问。
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
    ]
}

不要忘记确保您还在您的 INSTALLED_APPS 中添加了 rest_framework。

我们现在准备创建我们的 API 了。这是我们项目的根 urls.py 模块：

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

# 序列化器定义 API 表示。
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ('url', 'username', 'email', 'is_staff')

# ViewSets 定义视图行为。
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

# 路由器提供了一种自动确定 URL conf 的简便方法。
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)

# 使用自动 URL 路由连接我们的 API。
# 此外，我们还包含可浏览 API 的登录 URL。
urlpatterns = [
    url(r'^', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

您现在可以在浏览器中打开 API，网址为 http://127.0.0.1:8000/，并查看新的 “用户” API。如果您使用右上角的登录控件，您还可以从系统添加，创建和删除用户。

快速开始 (Quickstart)

迫不及待地想要开始？快速开始指南是启动和运行以及使用 REST framework 构建 API 的最快方法。

发展 (Development)

有关如何克隆存储库、运行测试套件并将更改提交回 REST framework 的信息，请参阅贡献指南。

支持 (Support)

要获得支持，请参阅 REST framework 讨论组，在 irc.freenode.net 上尝试 #restframework 通道，搜索 IRC 档案，或者对 Stack Overflow 提出问题，确保包含 ‘django-rest-framework’ 标签。

如需优先支持，请注册专业或高级赞助计划。

有关 REST framework 开发的更新，您可能还想在 Twitter 上关注作者。

Follow @_tomchristie

安全 (Security)

如果您认为您在 Django REST framework 中发现了具有安全隐患的内容，请不要在公共论坛中提出问题。

通过电子邮件将问题说明发送至 [email protected]。在任何公开披露之前，项目维护者将与您一起解决任何需要的问题。

执照 (License)

在满足下列条件的情况下，允许以源和二进制形式重新分配和使用，无论是否加以修改：

源代码的重新分发必须保留上述版权声明，此条件列表和以下免责声明。
以二进制形式重新发布必须在提供的文档和/或其他材料中复制上述版权声明、本条件列表和以下免责声明。

本软件由版权所有者和贡献者 “AS IS” 提供，任何明示或默示保证，包括，但不限于，对于特定用途的适销性和适用性的暗示保证不承担任何责任。在任何情况下，著作权人或贡献者不应对任何直接、间接、附带、特殊、惩戒性或相应的损害 (包括但不限于代用品或服务的采购；使用、数据或利润的损失；或业务中断) 负责，无论是在合同中，严格责任，或侵权 (包括过失或其他) 产生的任何方式使用本软件，即使被告知这种损害的可能性。

Home