快速入门

我们将创建一个简单的API 用于admin用户,在系统中 查看和编辑用户和组信息.


创建项目

创建一个叫tutorial  的项目 , 然后创建一个app 叫   quickstart

# 创建项目目录
mkdir tutorial
cd tutorial

################## 这里是非必须的 ################
# 创建一个虚拟环境,来隔离我们创建的包 的本地依赖, 
virtualenv env
source env/bin/activate  # On Windows use `env\Scripts\activate`

# 安装django 和django REST framework 到虚拟环境
pip install django
pip install djangorestframework
#############################################


# 创建一个新的项目 作为一个独立的程序
django-admin.py startproject tutorial .  # Note the trailing '.' character
cd tutorial
django-admin.py startapp quickstart


现在同步数据库

python manage.py makemigrations
python manage.py migrate



我们还将创建一个用户名为 admin 初始用户,密码为 password123 .稍后我们会在我们的例子中验证我们的用户.

python manage.py    createsuperuser


一旦 建立数据库 并创建初始用户 这些你准备好了, 那么 打开app的目录, 我们要开始写代码了.....



Serialiazers ( 序列化器)

首先我们要定义一些序列化器, 让我们创建一个叫  tutorial/quickstart/serializers.py  的新模块.

代码如下:

from django.contrib.auth.models import User, Group
from rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ('url', 'username', 'email', 'groups')
        
class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = ('url', 'name')


注意: 

    在这个例子中,我们使用了超链接关系 -- HyperlinkedModelSerializer , 你也可以使用  primary key 和其他各种关系.  不过 使用超链接 是比较好的 RESTful 设计方式.




views (视图)

好的, 现在我们最好写一些views了, 打开 tutorial/quickstart/views.py  然后输入如下内容:

from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer

class UserViewSet(viewsets.ModelViewSet):
    """
    API endpoint that allows users to be viewed or edited.
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    
class GroupViewSet(viewsets.ModelViewSet):
    """
    API endpoint that allows groups to be viewed or edited.
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer


与其写多个views ,不如把所所有的常见的行为进行分组,写到一个叫 ViewSet  的类里.

如果有需要我们,可以很容易的把这些分成独立的views ,但是使用 viewsets 可以保持view 逻辑的井井有条   和代码的清晰.




URLs

Okay, 现在我们向 tutorial/urls.py 文件中 配置 API URLs . 

from django.conf.urls import url, include
from rest_framework import routers
from tutorial.quickstart import views

router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)

# 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'))
]


由于我们使用了viewsets 而不是views , 我们可以通过使用一个router类  简单的注册viewsets  来为我们的 API 生成 URL 配置.

同样,如果需要对API URLs进行更多的操作,可以使用 基于views 的普通类,并明确的写入URL 配置里.

最后,我们保留默认的登陆注销views,供可浏览的API来使用.  这个是可选的,  除非你的 API 需要 身份验证并且你想使用可 浏览的API



setting 

我们还想设置一些全局配置 ,我们想打开分页功能, 希望我们的API仅可以被admin 用户连接, 

需要设置的模块是: tutorial/settings.py

INSTALLED_APPS = (
    ...
    'rest_framework',
)

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.IsAdminUser',),
    'PAGE_SIZE': 10
}

好了 ,到这里我们就做完了



测试我们的API

现在我们准更好了测试我们已经建立好的API ,从命令行启动我们的server

python manage.py runserver

现在我们可以链接我们的api ,无论是命令行 还是像curl一样的工具

bash: curl -H 'Accept: application/json; indent=4' -u admin:password123 http://127.0.0.1:8000/users/
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "admin@example.com",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/1/",
            "username": "admin"
        },
        {
            "email": "tom@example.com",
            "groups": [                ],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}


使用 命令行工具 httpie

bash: http -a admin:password123 http://127.0.0.1:8000/users/
HTTP/1.1 200 OK
...
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "admin@example.com",
            "groups": [],
            "url": "http://localhost:8000/users/1/",
            "username": "paul"
        },
        {
            "email": "tom@example.com",
            "groups": [                ],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}


直接通过浏览器访问

Quick start p_w_picpath


通过浏览器使用时,确认你使用了右上角的登陆按钮进行了登陆

这里就可以说 so easyle 

如果你想从头到尾更深入的了解REST framework 点击下面的链接:

 The tutorial, 

The API guide.