"Django REST Framework 是什麼？跟 Django 有什麼關係？"

"Django REST Framework（DRF）是建構於 Django 之上的第三方套件，由 Tom Christie 於 2011 年發布，專門用於開發 RESTful API。它提供 Serializer、ViewSet、Router、Authentication、Permissions 等完整工具，讓你可以快速將 Django Model 轉換為 JSON API，是 Python 生態系中建構 REST API 的事實標準。"

"REST API 的 HTTP 方法如何對應 CRUD 操作？"

"REST API 使用 HTTP 方法對應 CRUD 操作：GET 對應 Read（讀取資源）、POST 對應 Create（建立資源）、PUT 對應 Update（完整更新資源）、PATCH 對應 Update（部分更新資源）、DELETE 對應 Delete（刪除資源）。這是 RESTful 架構的核心設計原則之一。"

"DRF 的 Browsable API 是什麼？有什麼好處？"

"Browsable API 是 DRF 內建的自動化 HTML 介面，當你用瀏覽器直接訪問 API Endpoint 時，會看到一個可互動的頁面，顯示回應資料、可用的 HTTP 方法與表單。它讓開發者不需要額外工具就能測試 API，大幅提升開發階段的除錯效率。"

Django REST Framework 入門：建立你的第一個 API | Django 教學

Django REST Framework（簡稱 DRF）是 Python 生態系中建構 RESTful API 的事實標準框架，建構於 Django 之上，提供 Serializer（序列化器）、ViewSet、Router、Authentication（認證）與 Permissions（權限）等完整工具組。本文將從 REST API 的基礎概念出發，帶你安裝 DRF、建立第一個 API Endpoint，並認識 Browsable API 與 DRF 的核心組件，為後續深入學習打下基礎。

什麼是 REST API？

REST（Representational State Transfer，表現層狀態轉移）是一種軟體架構風格，由 Roy Fielding 於 2000 年在博士論文中提出。遵循 REST 原則的 API 稱為 RESTful API，它是現代 Web 應用程式中前後端溝通的主流方式。

RESTful 架構有幾個核心原則：

資源導向（Resource-Oriented）：每個 URL 代表一個資源，例如 /api/articles/ 代表文章列表、/api/articles/1/ 代表 ID 為 1 的文章
統一介面（Uniform Interface）：使用標準的 HTTP 方法（GET、POST、PUT、DELETE）操作資源
無狀態（Stateless）：每次請求都是獨立的，伺服器不儲存客戶端的狀態
可快取（Cacheable）：回應可以被標記為可快取或不可快取，提升效能
分層系統（Layered System）：客戶端不需要知道是直接連接伺服器還是中間的代理層

HTTP 方法與 CRUD 對應

REST API 使用 HTTP 方法（HTTP Methods）來定義對資源的操作，與資料庫的 CRUD（Create、Read、Update、Delete）操作有清楚的對應關係：

HTTP 方法	CRUD 操作	說明	範例 URL
`GET`	Read（讀取）	取得資源列表或單一資源	`GET /api/articles/`
`POST`	Create（建立）	建立新資源	`POST /api/articles/`
`PUT`	Update（完整更新）	更新整個資源，需提供所有欄位	`PUT /api/articles/1/`
`PATCH`	Update（部分更新）	只更新指定的欄位	`PATCH /api/articles/1/`
`DELETE`	Delete（刪除）	刪除指定資源	`DELETE /api/articles/1/`

理解這張對應表非常重要，因為 DRF 的 View 和 Router 都是圍繞這些 HTTP 方法設計的。

Django REST Framework 簡介

Django REST Framework（DRF）由 Tom Christie 於 2011 年發布，是一個建構於 Django 之上的強大 REST API 開發框架。它採用 BSD-2-Clause 授權，是開源社群中最受歡迎的 Python API 框架之一。

為什麼選擇 DRF？

完整的工具組：從序列化、驗證、認證到分頁，一個框架搞定
與 Django 深度整合：直接使用 Django Model、ORM、Authentication 系統
Browsable API：內建可操作的 HTML 測試介面
豐富的生態系：大量的第三方套件支援（JWT、OpenAPI 文件生成等）
成熟穩定：超過 10 年的發展歷史，廣泛用於生產環境

安裝 Django REST Framework

確保你已經有一個 Django 專案，接著安裝 DRF：

# 安裝 Django REST Framework
pip install djangorestframework

安裝完成後，將 rest_framework 加入 settings.py 的 INSTALLED_APPS：

# settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # 第三方套件
    'rest_framework',
    # 你的 App
    'articles',
]

接著可以在 settings.py 中加入 DRF 的全域設定：

# settings.py

REST_FRAMEWORK = {
    # 預設的 Renderer（渲染器）
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
    ],
    # 預設的 Parser（解析器）
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework.parsers.JSONParser',
        'rest_framework.parsers.FormParser',
        'rest_framework.parsers.MultiPartParser',
    ],
    # 預設的認證方式
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.BasicAuthentication',
    ],
    # 預設的權限設定
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.AllowAny',
    ],
}

在開發階段建議保留 BrowsableAPIRenderer，方便透過瀏覽器直接測試 API。正式環境中可以移除它，只保留 JSONRenderer。

建立第一個 API Endpoint

接下來我們從零開始建立一個完整的 API Endpoint，假設你已經有一個 articles App 和對應的 Model：

步驟一：確認 Model

# articles/models.py

from django.db import models

class Article(models.Model):
    title = models.CharField('標題', max_length=200)
    content = models.TextField('內容')
    created_at = models.DateTimeField('建立時間', auto_now_add=True)
    updated_at = models.DateTimeField('更新時間', auto_now=True)

    class Meta:
        ordering = ['-created_at']

    def __str__(self):
        return self.title

步驟二：建立 Serializer

Serializer（序列化器）是 DRF 的核心組件，負責將 Django Model 物件轉換為 JSON 格式（序列化），以及將客戶端傳來的 JSON 資料轉換回 Python 物件並進行驗證（反序列化）。

在 articles App 下建立 serializers.py：

# articles/serializers.py

from rest_framework import serializers
from .models import Article

class ArticleSerializer(serializers.ModelSerializer):
    """文章序列化器"""

    class Meta:
        model = Article
        fields = ['id', 'title', 'content', 'created_at', 'updated_at']
        read_only_fields = ['created_at', 'updated_at']

ModelSerializer 會根據 Model 的欄位定義自動生成對應的序列化欄位，包含驗證規則。read_only_fields 指定哪些欄位只能讀取、不接受寫入。

步驟三：建立 View

DRF 提供多種建立 View 的方式，最簡單的是使用 @api_view 裝飾器（Decorator）：

# articles/views.py

from rest_framework.decorators import api_view
from rest_framework.response import Response
from rest_framework import status
from .models import Article
from .serializers import ArticleSerializer

@api_view(['GET', 'POST'])
def article_list(request):
    """
    GET: 取得所有文章列表
    POST: 建立新文章
    """
    if request.method == 'GET':
        articles = Article.objects.all()
        serializer = ArticleSerializer(articles, many=True)
        return Response(serializer.data)

    elif request.method == 'POST':
        serializer = ArticleSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)


@api_view(['GET', 'PUT', 'DELETE'])
def article_detail(request, pk):
    """
    GET: 取得單一文章
    PUT: 更新文章
    DELETE: 刪除文章
    """
    try:
        article = Article.objects.get(pk=pk)
    except Article.DoesNotExist:
        return Response(
            {'error': '文章不存在'},
            status=status.HTTP_404_NOT_FOUND
        )

    if request.method == 'GET':
        serializer = ArticleSerializer(article)
        return Response(serializer.data)

    elif request.method == 'PUT':
        serializer = ArticleSerializer(article, data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

    elif request.method == 'DELETE':
        article.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

@api_view 裝飾器接收一個 HTTP 方法的列表，定義這個 View 可以處理哪些請求方法。Response 物件會根據客戶端的 Accept Header 自動選擇回應格式。

步驟四：配置 URL

# articles/urls.py

from django.urls import path
from . import views

urlpatterns = [
    path('api/articles/', views.article_list, name='article-list'),
    path('api/articles/<int:pk>/', views.article_detail, name='article-detail'),
]

別忘了在專案的主 urls.py 中 include 這個 App 的 URL：

# myproject/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('articles.urls')),
]

步驟五：測試 API

啟動開發伺服器後，可以透過多種方式測試 API：

# 啟動開發伺服器
python manage.py runserver

# 使用 curl 取得文章列表
curl http://127.0.0.1:8000/api/articles/

# 使用 curl 建立新文章
curl -X POST http://127.0.0.1:8000/api/articles/ \
  -H "Content-Type: application/json" \
  -d '{"title": "我的第一篇文章", "content": "這是透過 API 建立的文章"}'

# 使用 httpie（更友善的指令列 HTTP 工具）
http GET http://127.0.0.1:8000/api/articles/
http POST http://127.0.0.1:8000/api/articles/ title="Hello DRF" content="API 測試"

你也可以直接在瀏覽器輸入 http://127.0.0.1:8000/api/articles/，會看到 DRF 的 Browsable API 介面。

Browsable API 介面

Browsable API 是 DRF 最具特色的功能之一。當你用瀏覽器訪問 API Endpoint 時，DRF 會自動渲染一個可互動的 HTML 頁面，包含：

回應資料：以格式化的 JSON 顯示 API 回傳的資料
可用的 HTTP 方法：頁面上會顯示 GET、POST、PUT、DELETE 等按鈕
表單：提供 HTML 表單與 Raw JSON 輸入框，直接在瀏覽器中測試寫入操作
認證狀態：顯示目前的登入狀態

這讓你在開發階段完全不需要依賴 Postman 或 curl 就能快速測試 API，大幅提升開發效率。

如果你想在 Browsable API 中加入登入/登出功能，可以在主 urls.py 加入：

# myproject/urls.py

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

JSON 回應格式

DRF 預設以 JSON 格式回傳資料。以下是典型的 API 回應範例：

// GET /api/articles/ 的回應（列表）
[
    {
        "id": 1,
        "title": "Django 入門教學",
        "content": "Django 是一個 Python Web 框架...",
        "created_at": "2026-06-10T08:30:00Z",
        "updated_at": "2026-06-10T08:30:00Z"
    },
    {
        "id": 2,
        "title": "DRF 快速上手",
        "content": "Django REST Framework 是...",
        "created_at": "2026-06-10T09:00:00Z",
        "updated_at": "2026-06-10T09:00:00Z"
    }
]

// POST /api/articles/ 驗證失敗的回應
{
    "title": ["這個欄位是必須的。"],
    "content": ["這個欄位是必須的。"]
}

DRF 的錯誤回應會自動按照欄位名稱分組，方便前端逐一顯示驗證錯誤訊息。

DRF 核心組件概覽

DRF 提供了一整套完整的工具組件，以下是你在後續學習中會深入接觸的核心元素：

Serializers（序列化器）

負責資料的序列化（Model -> JSON）與反序列化（JSON -> Model），同時處理資料驗證。主要有 Serializer、ModelSerializer、HyperlinkedModelSerializer 三種。

Views（視圖）

DRF 提供多個層級的 View 抽象：

@api_view：函式導向，最簡單的方式
APIView：類別導向，提供更多控制
GenericAPIView + Mixins：組合常用的 CRUD 邏輯
ViewSet / ModelViewSet：最高層級的抽象，一個類別搞定所有 CRUD

Routers（路由器）

Router 搭配 ViewSet 使用，可以自動生成 URL patterns，不再需要手動定義每個 Endpoint 的 URL。

from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register(r'articles', ArticleViewSet)

urlpatterns = router.urls

Authentication（認證）

DRF 內建多種認證方式：SessionAuthentication、BasicAuthentication、TokenAuthentication。第三方套件如 djangorestframework-simplejwt 則提供 JWT（JSON Web Token）認證。

Permissions（權限）

控制誰可以存取哪些資源：AllowAny（任何人）、IsAuthenticated（已登入用戶）、IsAdminUser（管理員）、IsAuthenticatedOrReadOnly（已登入可寫，未登入只能讀）。也支援自訂權限類別。

Pagination（分頁）

當資料量龐大時，分頁是不可或缺的功能。DRF 提供 PageNumberPagination（頁碼分頁）、LimitOffsetPagination（偏移量分頁）與 CursorPagination（游標分頁）。

常用的 REST_FRAMEWORK 設定項

以下整理開發中常用的全域設定，放在 settings.py 的 REST_FRAMEWORK 字典中：

# settings.py

REST_FRAMEWORK = {
    # 分頁設定
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,

    # 認證方式
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ],

    # 權限設定
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',
    ],

    # 限流（Throttling）設定
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle',
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/hour',   # 匿名用戶每小時 100 次
        'user': '1000/hour',  # 登入用戶每小時 1000 次
    },

    # 日期時間格式
    'DATETIME_FORMAT': '%Y-%m-%dT%H:%M:%SZ',

    # 篩選後端
    'DEFAULT_FILTER_BACKENDS': [
        'django_filters.rest_framework.DjangoFilterBackend',
        'rest_framework.filters.SearchFilter',
        'rest_framework.filters.OrderingFilter',
    ],
}

每個設定項也可以在個別 View 中覆寫，提供了全域統一與局部客製化的彈性。

總結

本文從 REST API 的基礎概念開始，帶你完成了 Django REST Framework 的完整入門流程：

REST 原則：資源導向、統一介面、無狀態是 RESTful 架構的核心
HTTP 方法與 CRUD：GET/POST/PUT/PATCH/DELETE 分別對應讀取/建立/更新/刪除操作
安裝與設定：pip install djangorestframework，加入 INSTALLED_APPS 並配置 REST_FRAMEWORK
第一個 API：透過 Serializer 處理資料轉換、@api_view 處理請求邏輯、URL 配置路由
Browsable API：DRF 獨有的瀏覽器測試介面，開發階段的利器
核心組件：Serializers、Views、Routers、Authentication、Permissions、Pagination 構成 DRF 的完整功能體系

DRF 的設計哲學是「漸進式複雜度」——你可以從最簡單的 @api_view 開始，隨著需求成長逐步升級到 APIView、GenericAPIView，最終使用 ModelViewSet + Router 達到最高的開發效率。在接下來的教學中，我們將逐一深入每個核心組件，學習如何建構生產等級的 RESTful API。