---
# System prepended metadata

title: 步骤 1：了解API的基本概念
tags: [LeviLan, api]

---

步驟 1：了解API的基本概念
API（Application Programming Interface）是應用程式接口，允許不同的軟體系統之間進行通訊。 API文件通常會描述以下內容：

端點（Endpoints）：API的URL路徑。
請求方法（HTTP Methods）：如GET、POST、PUT、DELETE等。
參數（Parameters）：傳遞給API的數據，可以是查詢參數、請求體資料或路徑參數。
回應（Responses）：API回傳的資料格式及可能的狀態碼。
認證（Authentication）：如何驗證身分以存取受保護的資源。
步驟 2：仔細閱讀API文檔
找到基礎URL

API文件通常會提供一個基礎URL，例如：
```
https://api.example.com/v1/
```

這個URL是所有API請求的起點。
查看可用的端點

每個端點代表API的一個功能。例如：
GET /users：取得使用者清單。
POST /users：建立新使用者。
GET /users/{id}：取得特定使用者的詳細資訊。
理解請求方法

不同的HTTP方法有不同的用途：
GET：取得數據。
POST：發送資料以建立資源。
PUT：更新現有資源。
DELETE：刪除資源。
檢查請求參數

參數可能是：
查詢參數：附加在URL後面，例如?page=1&limit=10。
路徑參數：嵌入在URL中，例如/users/{id}。
請求體參數：用於POST或PUT請求，通常是JSON格式。
查看回應格式

回應通常以JSON格式傳回。例如：
```
{
    "status": "success",
    "data": [
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"}
    ]
}
```

注意認證要求

如果API需要認證，通常會提到以下幾種方式：
API金鑰：透過請求頭或查詢參數傳遞。
OAuth令牌：透過請求頭傳遞，例如Authorization: Bearer <token>。
步驟 3：使用Python呼叫API
假設我們有一個範例API文件如下：

基礎URL：https://api.example.com/v1/
端點：GET /users，用於取得使用者清單。
認證：需要在請求頭中新增API金鑰。
範例程式碼
```
import requests

# 定義基礎URL和端點
base_url = "https://api.example.com/v1"
endpoint = "/users"

# 定義API密鑰
api_key = "your_api_key_here"

# 構造完整的URL
url = base_url + endpoint

# 設置請求header包含認證訊息
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# 發送GET請求
try:
    response = requests.get(url, headers=headers)

    # 檢查響應狀態碼
    if response.status_code == 200:
        data = response.json()  # 解析JSON響應
        print("成功獲取數據：", data)
    else:
        print(f"請求失敗，狀態碼：{response.status_code}")
        print("錯誤訊息：", response.text)

except requests.exceptions.RequestException as e:
    print("請求過程中發生錯誤：", e)
``` 
  步驟 4：處理常見問題
狀態碼含義
200 OK：請求成功。
400 Bad Request：請求參數有誤。
401 Unauthorized：認證失敗。
404 Not Found：資源不存在。
500 Internal Server Error：伺服器內部錯誤。
調試技巧
列印完整的請求URL和參數，確保它們正確。
使用工具（如Postman）手動測試API。
檢查API文檔中的範例請求和回應。
錯誤處理

在程式碼中加入異常處理，確保程式不會因網路問題或API錯誤而崩潰。
    
步驟 5：優化和擴展
1. 封裝為函數
將API呼叫邏輯封裝到一個函數中，可以提高程式碼的複用性和可讀性。例如：    
```
import requests

def call_api(method, endpoint, api_key, params=None, data=None):
    """
    封装API调用逻辑。
    
    参数：
        method (str): 请求方法，如 "GET", "POST", "PUT", "DELETE"。
        endpoint (str): API端点路径，例如 "/users"。
        api_key (str): API密钥。
        params (dict, optional): 查询参数，例如 {"page": 1, "limit": 10}。
        data (dict, optional): 请求体数据（用于 POST 或 PUT 请求）。
    
    返回：
        dict: 解析后的JSON响应数据。
    """
    base_url = "https://api.example.com/v1"
    url = base_url + endpoint

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    try:
        # 根据请求方法发送请求
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=data)
        elif method.upper() == "PUT":
            response = requests.put(url, headers=headers, json=data)
        elif method.upper() == "DELETE":
            response = requests.delete(url, headers=headers)
        else:
            raise ValueError("不支持的请求方法")

        # 检查状态码并处理响应
        if response.status_code == 200 or response.status_code == 201:
            return response.json()
        else:
            print(f"请求失败，状态码：{response.status_code}")
            print("错误信息：", response.text)
            return None

    except requests.exceptions.RequestException as e:
        print("请求过程中发生错误：", e)
        return None
```
使用範例：
```
# 获取用户列表
api_key = "your_api_key_here"
endpoint = "/users"
params = {"page": 1, "limit": 10}

result = call_api("GET", endpoint, api_key, params=params)
if result:
    print("用户列表：", result)

# 创建新用户
new_user_data = {"name": "Alice", "email": "alice@example.com"}
result = call_api("POST", "/users", api_key, data=new_user_data)
if result:
    print("创建用户成功：", result)
```
2. 使用環境變數管理敏感資訊
API金鑰等敏感資訊不應硬編碼在程式碼中，而是應該透過環境變數或設定檔管理。可以使用os模組讀取環境變數：
```
import os

# 从环境变量中读取API密钥
api_key = os.getenv("API_KEY")
if not api_key:
    raise ValueError("未找到API密钥，请设置环境变量API_KEY")
```
運行程式前，確保設定了環境變數：
```
export API_KEY="your_api_key_here"
```
3. 使用第三方函式庫簡化請求
除了requests，還可以使用更進階的函式庫（如httpx或requests-cache）來增強功能：

httpx：支援非同步請求。
requests-cache：快取API回應以減少重複請求。
範例（使用httpx進行非同步請求）：
```
import httpx
import asyncio

async def fetch_users(api_key):
    url = "https://api.example.com/v1/users"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        if response.status_code == 200:
            return response.json()
        else:
            print(f"请求失败，状态码：{response.status_code}")
            return None

# 调用异步函数
api_key = "your_api_key_here"
result = asyncio.run(fetch_users(api_key))
print("用户列表：", result)
```
4. 處理分頁數據
許多API回傳的資料是分頁的。可以透過循環請求所有頁面來獲取完整資料。例如：
```
def fetch_all_users(api_key):
    base_url = "https://api.example.com/v1/users"
    headers = {"Authorization": f"Bearer {api_key}"}
    all_users = []
    page = 1

    while True:
       
```