---
title: 'RESTful API 筆記'
---

RESTful API 筆記
===
RESTful（Representational State Transfer，表徵狀態轉移）API 是一種網絡應用程序的接口設計風格，依賴於HTTP/HTTPS協議。它使用標準的HTTP方法（如GET、POST、PUT、DELETE等）來執行資源的操作。
RESTful API 通常會搭配 HTTP 回應狀態碼（HTTP response status codes）來表示請求的結果。這些狀態碼提供了關於請求是否成功，以及如果不成功，原因何在的重要信息。

核心概念
---

1. 資源（Resource）
- 資源的表現層：資源可以是文本、JSON、XML 或其他格式。
- 統一資源標識符（URI）：每個資源都有唯一的URI。例如，/users 可以代表用戶資源。
2. 狀態無關（Stateless）
- 無狀態通信：每次請求都包含所有必要信息。伺服器不保存客戶端的任何請求狀態。
3. 可緩存（Cacheable）
- 提高效率：響應可以被標記為可緩存或不可緩存，減少客戶端-伺服器間的交互。

HTTP方法
---
- GET：獲取資源。
- POST：創建新資源。
- PUT：更新現有資源。
- DELETE：刪除資源。
- PATCH：局部更新資源。

備注: 通常PATCH以及PUT是相同概念，不過爲了數據完整性，基本上都會使用PUT

API 設計的核心原則
---
- 客戶端-伺服器分離：客戶端和伺服器之間的分離使得每部分可以獨立發展。
- 無狀態操作：每次請求都應包含所有必要的信息，伺服器不保存任何客戶端的上下文。
- 可通過網絡緩存提高效能：通過設置緩存策略，可以提高API的效率和性能。
- 統一接口：保持一致的接口設計，使API更容易理解和使用。
- 按需編碼（選用）：根據需求提供可執行的代碼或腳本，但這通常不常見。

路由設計的核心原則
---

- 清晰且描述性的URL：使用名詞而非動詞來命名URL，並清楚地表示資源。
- 使用標準HTTP方法：如GET（讀取）、POST（創建）、PUT（更新）、DELETE（刪除）來處理資源。
- 資源層次結構：通過路徑來表達資源之間的層次關係，例如 /users/{id}/posts。
- 統一資源定位：相同的資源應該在所有的操作中保持一致的URI。
- 狀態代碼使用：使用HTTP狀態代碼來表示API操作的結果（如200成功，404未找到，500服務器錯誤等）。
- 過濾、排序和分頁：提供過濾、排序和分頁功能來改善大型數據集的處理。

實際範例
---
以下是一個基於PHP和Laravel框架的RESTful API範例:

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\UserController;

// 使用UserController中的方法來處理對應的HTTP請求
Route::get('/users', [UserController::class, 'index']);
Route::post('/users', [UserController::class, 'store']);
Route::get('/users/{id}', [UserController::class, 'show']);
Route::put('/users/{id}', [UserController::class, 'update']);
Route::delete('/users/{id}', [UserController::class, 'destroy']);

use App\Models\User;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;

class UserController extends Controller
{
    // 獲取所有用戶
    public function index()
    {
        return User::all();
    }

    // 創建新用戶
    public function store(Request $request)
    {
        $validatedData = $request->validate([
            'name' => 'required|max:255',
            'email' => 'required|email|unique:users',
            'password' => 'required|min:6'
        ]);

        $user = User::create($validatedData);

        return response()->json($user, 201);
    }

    // 獲取單個用戶
    public function show($id)
    {
        return User::findOrFail($id);
    }

    // 更新用戶
    public function update(Request $request, $id)
    {
        $user = User::findOrFail($id);
        $user->update($request->all());

        return response()->json($user, 200);
    }

    // 刪除用戶
    public function destroy($id)
    {
        User::findOrFail($id)->delete();
        return response()->json(null, 204);
    }
}

這些路由對應於不同的HTTP方法和URL，並連接到UserController中的相應方法。每個路由處理特定的API請求：

- GET /users：獲取所有用戶的列表。
- POST /users：創建一個新用戶。
- GET /users/{id}：獲取特定ID的用戶。
- PUT /users/{id}：更新特定ID的用戶。
- DELETE /users/{id}：刪除特定ID的用戶。

在設計API路由時，重要的是要保持路由清晰且符合REST原則，這樣客戶端開發者能夠輕鬆地理解和使用您的API。

總結
---
雖然某些時候在設計API路由的時候往往會使用功能去設計命名（如:`/users/getUsersInfo`），這樣違反的RESTful API的設計理念，所以設計的時候要去思考資料來源。
RESTful API的設計理念在於簡潔和統一，使得API易於理解和使用。這種方法強調資源和其表達，並通過HTTP協議的標準操作來處理這些資源。遵循REST原則的API能夠提供良好的性能、可擴展性和可維護性，同時也簡化了客戶端和服務端的交互。這種設計方式適用於多種不同的應用程序，從簡單的資料存取到複雜的業務邏輯處理。

參考資料:
---
- [API 是什麼? RESTful API 又是什麼?](https://medium.com/itsems-frontend/api-%E6%98%AF%E4%BB%80%E9%BA%BC-restful-api-%E5%8F%88%E6%98%AF%E4%BB%80%E9%BA%BC-a001a85ab638)
- [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)