我們將創(chuàng)建一個簡單的API惩激,以允許管理員用戶查看和編輯系統(tǒng)中的用戶和組
Project setup
創(chuàng)建一個叫tutorial的新Django項目,然后啟動一個名為quickstart的新應用程序蒜哀。
# Create the project directory
mkdir tutorial
cd tutorial
# Create a virtualenv to isolate our package dependencies locally
virtualenv env
source env/bin/activate # On Windows use `env\Scripts\activate`
# Install Django and Django REST framework into the virtualenv
pip install django
pip install djangorestframework
# Set up a new project with a single application
django-admin.py startproject tutorial . # Note the trailing '.' character
cd tutorial
django-admin.py startapp quickstart
cd ..
現(xiàn)在第一次同步你的數據庫:
python manage.py migrate
隨后,我們還將創(chuàng)建一個名為admin的初始用戶县耽,密碼為password123至耻。 我們稍后將在該示例中驗證該用戶亲怠。
python manage.py createsuperuser
一旦你創(chuàng)建了一個數據庫所计,初始用戶創(chuàng)建完成并準備好了一切,那么就打開應用程序的目錄团秽,我們將要開始編碼了...
Serializers
首先我們要定義一些序列化程序主胧。 創(chuàng)建一個名為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夷都。 你還可以使用主鍵和各種其他關系,但超鏈接是很好的符合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
我們將所有常見行為分組到ViewSets的類中党饮,而不是寫多個視圖。
如果需要驳庭,我們當然可以容易地劃分為獨立的視圖刑顺,但是使用viewsets可以使視圖邏輯組織更良好、簡潔饲常。
URLs
好了蹲堂,我們現(xiàn)在開始在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贝淤,所以我們可以簡單地使用路由器類注冊viewsets 來自動生成API的URL 配置柒竞。
再次說一下,如果我們需要對API URL進行更多的控制霹娄,我們可以簡單地將其下拉到使用常規(guī)基于類的視圖能犯,并明確地編寫URL 配置。
最后犬耻,使用可瀏覽的API講包含默認的登錄和注銷視圖踩晶。 當然,這是可選的枕磁,但如果你的API需要身份驗證渡蜻,并且您想要使用可瀏覽的API,那么它們很有用。
Settings
我們也會想要一些全局設置茸苇。 例如我們想分頁排苍,我們希望我們的API只能由管理員使用。 這個設置模塊就在tutorial / settings.py中
INSTALLED_APPS = (
...
'rest_framework',
)
REST_FRAMEWORK = {
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.IsAdminUser',
],
'PAGE_SIZE': 10
}
好了学密,我們完成了淘衙。
Testing our API
現(xiàn)在,我們可以測試我們構建的API了腻暮。 從命令行啟動服務器彤守。
python manage.py runserver
我們現(xiàn)在可以從命令行訪問我們的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"
}
]
}
或直接通過瀏覽器具垫,跳轉到URL http://127.0.0.1:8000 / users / ...
如果您正在使用瀏覽器,請確保使用右上角的控件進行登錄试幽。
太好了筝蚕,那很簡單!
如果你想更深入地了解REST框架铺坞,請閱讀the tutorial 或者 API guide起宽。