---

Django REST Framework

Django REST Framework 是一个强大且灵活的工具包，用于构建 Web API。

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

• 可通过 Web 浏览的 API 对您的开发人员来说是一项巨大的可用性优势。
• 认证策略，包括用于 OAuth1a 和 OAuth2 的软件包。
• 序列化，支持 ORM 和 非 ORM 数据源。
• 完全可自定义 - 如果您不需要 更多 强大 功能，只需使用 常规基于函数的视图。
• 广泛的文档，以及 强大的社区支持。
• 受到包括 Mozilla、Red Hat、Heroku 和 Eventbrite 在内的国际公认公司的使用和信赖。

---

资金

REST Framework 是一个协作资助项目。如果您在商业上使用 REST Framework，我们强烈建议您通过注册付费计划投资于其持续发展。

每一次注册都能帮助我们使 REST Framework 在长期内实现财务可持续发展。

• Sentry
• Stream
• Spacinov
• Retool
• bit.io
• PostHog
• CryptAPI
• FEZTO
• Svix

非常感谢我们所有的 优秀赞助商，尤其是我们的高级支持者 Sentry、Stream、Spacinov、Retool、bit.io、PostHog、CryptAPI、FEZTO 和 Svix。

---

要求

REST Framework 需要以下内容

• Python (3.6、3.7、3.8、3.9、3.10、3.11)
• Django (3.0、3.1、3.2、4.0、4.1、4.2、5.0)

我们强烈建议并且仅正式支持每个 Python 和 Django 系列的最新补丁版本。

以下软件包是可选的

• PyYAML、uritemplate（5.1+、3.0.0+）——模式生成支持。
• Markdown（3.0.0+）——可浏览 API 的 Markdown 支持。
• Pygments（2.4.0+）——向 Markdown 处理添加语法高亮。
• django-filter（1.0.1+）——过滤支持。
• django-guardian（1.1.1+）——对象级别权限支持。

安装

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

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

...或从 github 克隆项目。

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

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

INSTALLED_APPS = [
    ...
    'rest_framework',
]

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

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

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

示例

让我们快速了解一下使用 REST 框架构建简单模型支持的 API。

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

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

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'
    ]
}

不要忘记确保您已将 rest_framework 添加到您的 INSTALLED_APPS 中。

我们现在可以创建我们的 API 了。以下是我们项目的根 urls.py 模块

from django.urls import path, 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 = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

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

快速入门

迫不及待地想开始？快速入门指南 是使用 REST 框架启动和运行以及构建 API 的最快方式。

开发

请参阅 贡献指南，了解有关如何克隆存储库、运行测试套件以及将更改贡献回 REST 框架的信息。

支持

如需支持，请参阅 REST 框架讨论组，尝试 irc.libera.chat 上的 #restframework 频道，或在 Stack Overflow 上提出问题，确保包含 'django-rest-framework' 标签。

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

安全

安全问题由 Django 安全团队 负责监督处理。

请通过电子邮件 security@djangoproject.com 报告安全问题.

在任何公开披露之前，项目维护人员将与您合作解决任何必要的问题。

许可证

版权所有 © 2011-至今，Encode OSS Ltd。保留所有权利。

允许重新分发和使用源代码和二进制形式，无论是否修改，只要满足以下条件

• 源代码的重新分发必须保留上述版权声明、条件列表和以下免责声明。

• 二进制形式的重新分发必须在文档和/或随分发提供的其他材料中复制上述版权声明、条件列表和以下免责声明。

• 未经事先明确书面许可，不得使用版权持有者的名称或其贡献者的名称来认可或推广源自本软件的产品。

本软件由版权持有者和贡献者“按原样”提供，并且任何明示或暗示的保证，包括但不限于对适销性和特定用途适用性的暗示保证，均被否认。在任何情况下，版权持有者或贡献者均不对任何直接、间接、偶然、特殊、惩戒性或后果性损害（包括但不限于采购替代商品或服务；使用、数据或利润损失；或业务中断）负责，无论其原因如何，也不论是在合同、严格责任或侵权（包括疏忽或其他）中，无论如何因使用本软件而产生，即使已告知此类损害的可能性。