什麼是 RESTful API？

REST（Representational State Transfer）是一種軟體架構風格，用於設計網路服務。RESTful API 遵循 REST 原則，提供一致且直觀的方式來操作資源。

核心原則核心原則

統一介面（Uniform Interface）
所有資源都通過統一的介面進行操作，使用標準的 HTTP 方法。

無狀態（Stateless）
每個請求都包含處理該請求所需的所有資訊，伺服器不保存客戶端狀態。

可快取（Cacheable）
回應應該明確標示是否可以快取，以提高效能。

分層系統（Layered System）
客戶端無法判斷是直接連接到終端伺服器，還是連接到中間層。

HTTP 方法對應

URL 設計規範

使用名詞，不用動詞

✅ 正確：GET /users
❌ 錯誤：GET /getUsers

使用複數形式

✅ 正確：/users, /products, /orders
❌ 錯誤：/user, /product, /order

階層關係表示

GET /users/123/orders # 獲取用戶 123 的所有訂單
GET /users/123/orders/456 # 獲取用戶 123 的訂單 456

查詢參數用於篩選和分頁

GET /users?page=2&limit=10&status=active
GET /products?category=electronics&sort=price&order=desc

HTTP 狀態碼

成功回應 (2xx)

• 200 OK – 請求成功
• 201 Created – 資源創建成功
• 204 No Content – 請求成功但無回應內容（通常用於 DELETE）

客戶端錯誤 (4xx)

• 400 Bad Request – 請求語法錯誤
• 401 Unauthorized – 需要驗證
• 403 Forbidden – 禁止訪問
• 404 Not Found – 資源不存在
• 405 Method Not Allowed – HTTP 方法不被允許
• 422 Unprocessable Entity – 請求格式正確但語義錯誤

伺服器錯誤 (5xx)

• 500 Internal Server Error – 伺服器內部錯誤
• 502 Bad Gateway – 網關錯誤
• 503 Service Unavailable – 服務暫時無法使用

回應格式規範

成功回應範例

{
    "success": true,
    "data": {
        "id": 123,
        "name": "John Doe",
        "email": "john@example.com"
    },
    "message": "User retrieved successfully"
}

錯誤回應範例

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Email is required",
        "details": {
            "field": "email",
            "value": null
        }
    }
}

列表回應範例

{
    "success": true,
    "data": [
        {"id": 1, "name": "User 1"},
        {"id": 2, "name": "User 2"}
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total": 100,
        "total_pages": 10
    }
}

版本控制

URL 路徑版本控制

GET /v1/users
GET /v2/users

Header 版本控制

GET /users
Accept: application/vnd.api+json;version=1

認證與授權

Bearer Token

Authorization: Bearer your_access_token_here

API Key

X-API-Key: your_api_key_here

最佳實踐

使用 HTTPS
所有 API 端點都應該使用 HTTPS 來確保資料傳輸安全。

提供清楚的錯誤訊息
錯誤回應應該包含足夠的資訊讓開發者理解問題所在。

實作速率限制

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

使用適當的 Content-Type

Content-Type: application/json
Content-Type: application/xml

支援 CORS

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

常見 API 端點範例

# 用戶管理
GET    /users           # 獲取用戶列表
POST   /users           # 創建新用戶
GET    /users/{id}      # 獲取特定用戶
PUT    /users/{id}      # 更新用戶
DELETE /users/{id}      # 刪除用戶

# 文章管理
GET    /posts           # 獲取文章列表
POST   /posts           # 創建新文章
GET    /posts/{id}      # 獲取特定文章
PUT    /posts/{id}      # 更新文章
DELETE /posts/{id}      # 刪除文章

# 巢狀資源
GET    /users/{id}/posts        # 獲取用戶的文章
POST   /users/{id}/posts        # 為用戶創建文章
GET    /posts/{id}/comments     # 獲取文章的評論

$birthDate = "1970-01-05";
$currentDate = date("d-m-Y");
$age = date_diff(date_create($birthDate), date_create($currentDate));
echo "Current age is ".$age->format("%y");
// Current age is 52

PHP_EOL = cross-platform-compatible newline character

PHP_EOL is ostensibly used to find the newline character in a cross-platform-compatible way, so it handles DOS/Unix issues.

Note that PHP_EOL represents the endline character for the current system. For instance, it will not find a Windows endline when executed on a unix-like system.

Example (Save the $DataArray to $filename):

file_put_contents($filename, implode(PHP_EOL, $DataArray), LOCK_EX);

Reference:
Adam Bellaire (2008), https://stackoverflow.com/questions/128560/when-do-i-use-the-php-constant-php-eol

// PHP 7.4 and later
print_r(array_filter($linksArray, fn($value) => !is_null($value) && $value !== ''));

// PHP 5.3 and later
print_r(array_filter($linksArray, function($value) { return !is_null($value) && $value !== ''; }));

// PHP < 5.3
print_r(array_filter($linksArray, create_function('$value', 'return $value !== "";')));

Reference:

BoltClock (2020), https://stackoverflow.com/questions/3654295/remove-empty-array-elements

source : https://askubuntu.com/questions/1146109/how-to-update-upgrade-php-7-2-to-latest-version-safely

sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php7.3 # The latest version in this repo for 18.04 is currently php7.4.  

apt-cache search php7.3 | grep php7.3  

apt install $(apt list --installed | grep php7.2- | cut -d'/' -f1 | sed -e 's/7.2/7.3/g')