RESTful API 規格參考指南

什麼是 RESTful API?

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

核心原則核心原則

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

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

可快取(Cacheable)
回應應該明確標示是否可以快取,以提高效能。

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

HTTP 方法對應

HTTP 方法用途範例 URL說明
GET讀取資源GET /users獲取所有用戶
GET讀取單一資源GET /users/123獲取 ID 為 123 的用戶
POST創建資源POST /users創建新用戶
PUT完整更新資源PUT /users/123完整更新用戶 123
PATCH部分更新資源PATCH /users/123部分更新用戶 123
DELETE刪除資源DELETE /users/123刪除用戶 123

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 # 獲取文章的評論

Age calculate in PHP

$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 is newline character in a cross-platform-compatible

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

Remove empty array elements

// 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

update/upgrade PHP 7.2 to latest version

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') 

自建了 php autoload ,並同時使用 composer 的 autoload,應該注意什麼?

不知道大家有沒有看過下面的 php autoload 教學?

Eric G. Huang 不像樣工程師
PHP系列 – Autoload 自動載入
http://justericgg.logdown.com/posts/196891-php-series-autoload

跟據這個教學,我解決了很多 class include require 檔案引入的困難,而且用了很長時間。

下面提供一些參考資料,讓大家可以分享。

Composer Basic usage: autoloading
https://getcomposer.org/doc/01-basic-usage.md#autoloading

PHP PSR-4 Autoloader 機制
http://blog.tonycube.com/2016/09/php-psr-4-autoloader.html

什麼是 PHP Standards Recommendations(PSR)(PHP標準建議)?
https://www.php-fig.org/psr/

PHP PSR-4 Autoloader 機制
http://blog.tonycube.com/2016/09/php-psr-4-autoloader.html

Composer Basic usage: autoloading
https://getcomposer.org/doc/01-basic-usage.md#autoloading

運用Composer Autoloader

1. 準備自建的 namespace 和 目錄位置

e.g. 
namespace1 = application\control\, 目錄位置 = {user_directory}/application/control 
namespace2 = application\module\, 目錄位置 = {user_directory}/application/module 
namespace3 = application\mouule\sql\, 目錄位置 = {user_directory}/application/module/sql
Class 例子:

<?php
//application/module/config.php

namespace application\module;

class config
{


    function __construct() {
        ...
    }
}

2. 在 composer.json 加入自建的 namespace 和 目錄位置

{
    "autoload": {
        "psr-4": {
            "application\\control\\": "application/control/",
            "application\\module\\": "application/module/",
            "application\\module\\sql\\": "application/module/sql/"
        }
    }
}

3. 進入 console mode,使用用戶權限及用戶的root目錄,執行下面的程式

composer dump-autoload

4. 在需要的php 程式中,頂部加入(因為我的 composer 是放在 /vendor中,請自行改進)

require __DIR__ . '/vendor/autoload.php';