Django REST 框架是一个用于构建 Web API 的强大而灵活的工具包。

您可能想要使用 REST 框架的一些原因：

• Web 可浏览的 API 为您的开发人员带来了巨大的可用性提升。
• 身份验证策略包含 OAuth1a 和 OAuth2 的软件包。
• 支持 ORM 和非 ORM 数据源的序列化。
• 可完全自定义 - 如果您不需要更强大的功能，只需使用常规的基于函数的视图即可。
• 丰富的文档和强大的社区支持。
• 受到 Mozilla、Red Hat、Heroku 和 Eventbrite 等国际知名公司的使用和信赖。

要求

REST 框架需要以下软件包：

• Django (4.2、5.0、5.1、5.2)
• Python (3.9、3.10、3.11、3.12、3.13)
  我们强烈建议使用并仅官方支持每个 Python 和 Django 系列的最新补丁版本。

以下软件包是可选的：

• PyYAML、uritemplate (5.1+、3.0.0+) - 支持 Schema 生成。
• Markdown (3.3.0+) - 支持 Markdown 可浏览 API。
• Pygments (2.7.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 Framework 构建简单的模型支持 API 的简单示例。

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

REST Framework 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 Framework 以及使用 REST Framework 构建 API 的最快方法。

开发

有关如何克隆代码库、运行测试套件以及帮助维护 REST Framework 代码库的信息，请参阅贡献指南。

支持

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

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

安全

请发送电子邮件至 security@encode.io 报告安全问题。

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

许可证

版权所有 © 2011-至今，Encode OSS Ltd. 保留所有权利。
允许以源代码和二进制形式重新分发和使用，无论是否经过修改，只要满足以下条件：

• 源代码的重新分发必须保留上述版权声明、本条件列表以及以下免责声明。
• 二进制形式的重新分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、本条件列表以及以下免责声明。
• 未经事先明确书面许可，不得使用版权所有者或其贡献者的名称来认可或推广本软件的衍生产品。