django rest framework quickstart

翻譯自django rest framework官方文檔, 版本3.1,原文地址http://www.django-rest-framework.org/

Quickstart

我們將創建一個簡單的API來允許管理員用戶查看和修改系統用戶和組.

Project setup

創建一個新的django project叫tutorial,然後創建一個新app叫quickstart.

# 創建工程目錄
mkdir tutorial
cd tutorial

# 在本地創建一個virtualenv來孤立依賴包
virtualenv env
source env/bin/activate # 在windows中使用 'env\Scripts\active'

# 在virtualenv中安裝django和django REST framework
pip install django
pip install djangorestframework

# 創建一個工程,只有一個應用
django-admin.py startproject tutorial.  # 注意結尾的"."字符(注:這是什麼意思,我也不知道)
cd tutorial
django-admin.py startapp quickstart
cd ..

然後首次同步數據庫:

python manage.py migrate

然後創建一個初始化用戶名字是admin,密碼是passwor.我們將會在例子裏驗證這個用戶.

python manage.py createsuperuser

如果你已經安裝了數據庫並且創建了初始化用戶,打開應用目錄,開始寫代碼…

Serializers

首先我們要定義一些序列化器.創建一個新模塊叫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使用了hyperlinked關聯.你也可以使用主鍵或者其他關聯,但hyperlinked適合RESTful設計.

Views

好了,我們接下來寫一些視圖.打開tutorial/quickstart/views開始寫代碼.

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端,允許查看和編輯users
    '''
    queryset = User.objects.all()
    serializer_class = UserSerializer

class GroupViewSet(viewsets.ModelViewSet):
    '''
    API端,允許查看和編輯groups
    '''
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

我們把一些通用操作一起封裝到了ViewSets裏,而不用寫很多views.
如果有需要的話,我們可以很容易的把他們分成許多views,但是使用viewsets能很好的組織視圖邏輯,保持簡練.
在某些情況下,你可以很容易地設置ViewSet類的model屬性,serializer和queryset就會自動的生成.設置queryset或serializer_class屬性能使你更顯式控制API的
行爲,這也是大多數應用推薦的方式.

URLS

OK,現在讓我們配置API的URL,請看tutorial/urls.py…

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

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

# 使用自動化URL routing配置API
# 另外,還需要可瀏覽的API的登錄用的URL
urlpatterns = [
    url(r'^', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

因爲我們使用的是viewsets而不是views,所以我們很簡單的在router類裏註冊viewsets就可以爲API自動生成URL配置.
如果我們需要對API URL更多的控制,我們可以很容易的不使用這些,而是直接使用views,並且顯式的寫URL配置.
最後,API的瀏覽控制需要默認的登錄和註銷views.這是可選的,但是如果你的API需要認證,而且你想使用API瀏覽控制,就很必要了.

Settings

我們還要做一些全局設置.我們會想要翻頁,想要不只是管理員用戶使用API.settings模塊在tutorial/settings.py裏

INSTALL_APPS = (
    ...
    'rest_frameword',
)

REST_FRAMEWORD = {
    'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.ISAdminUser'),
    'PAGE_SIZE': 10
}

OK,我們完成了

Testing our API

我們準備要測試我們創建的API了,讓我們通過命令行來啓動服務器.

python ./manage.py runserver

我們可以在命令行裏使用想curl這樣的工具來訪問API,…

bash:curl -H 'Accept:application/json;indent=4' -u admin:password http://127.0.0.1:8000/users/
{
    "count": 2,
    "next": null,
    "previous": null,
    "result":[
        {
            "email": "[email protected]",
            "groups":[],
            "url": "http://127.0.0.1:8000/users/1/",
            "username": "admin"
        },

        {
            "email": "[email protected]",
            "groups":[],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

或者命令行工具httpie

bash: http -a username:password http://127.0.0.1:8000/users/

HTTP/1.1 200 OK
...
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "[email protected]",
            "groups": [],
            "url": "http://localhost:8000/users/1/",
            "username": "paul"
        },
        {
            "email": "[email protected]",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

或者直接使用瀏覽器
如果你使用的是瀏覽器,確保使用右上角的control先登錄.