使用這些基本 REST API 最佳實踐構建出色的 API
你可能也喜歡這些API文章!
在使用和構建 API 方面，Python 應用程序是最受歡迎的選擇之一。在 Python 生態系統中，許多不同的框架（例如Django和Flask?）允許用戶構建廣泛的 API 套件。許多人轉向 Python請求等主要工具來在 Python 應用程序中使用 API。
如果您訪問了此博客，您很可能需要在應用程序中使用 API 并希望了解如何操作。嗯，你很幸運！在本博客中，我們將介紹如何在 Python 應用程序中使用 API、狀態代碼、如何設置查詢參數，以及如何使用 API 調用發送或接收的 JSON 數據。讓我們從基礎知識開始，看看 API 究竟是什么。
您可能知道，API 代表應用程序編程接口。 API 的核心是一組允許不同軟件應用程序相互通信的規則。它是不同軟件系統之間的橋梁，使它們能夠以結構化和安全的方式交互和交換數據。用戶可以向API發送請求，API將返回某種類型的響應。
更進一步，您可以將 API 視為數據的郵政服務。與通過郵政服務發送和接收信件和包裹類似，軟件應用程序使用 API 來發送和接收數據。 API 定義了正確的地址格式（端點）、允許的郵件類型（請求類型）以及您期望收到的返回內容（響應）。
API 幾乎為我們現實世界中數字生活的方方面面提供支持。 API 具有廣泛的用途，您每天可能會經歷多次（可能是數百或數千次）。以下是一些常見示例：
API 在現代軟件開發中至關重要，因為它們允許創建靈活的模塊化軟件系統。通過使用 API，開發人員可以構建現有服務的功能，加快開發過程并實現更復雜的功能。例如，支付處理 API（例如Stripe?）可以允許多家公司處理支付，而無需自己構建此類服務。
在 Python 代碼中使用 API 時，您首先需要弄清楚您將發出什么類型的 API 請求。 API 請求可以有不同的類型，通常稱為方法。這些方法每個都有一個與其關聯的唯一 HTTP 動詞以及基于該動詞的特定功能。以下是四種最常見的類型。
您需要根據您嘗試通過 API 完成的操作類型來選擇正確的端點和動詞。例如，我們可能有一個名為/users端點，它根據請求的類型執行不同的功能。如果發出GET請求，可能會返回用戶列表，而如果發出POST請求，可能會根據 API 收到的數據創建一個新用戶。
為了實際發出 API 請求，Python 有幾個可以使用的庫。一些最受歡迎的包括：
當比較這三個庫并決定使用哪一個時，選擇相對容易。本質上，它們三個都適用于我們在本博客中討論的基本操作。然而，隨著事情變得更加復雜，您可能需要更深入地了解差異化因素。下面讓我們快速瀏覽一下這些內容。
決定要使用哪個庫后，您需要在 Python 代碼中包含依賴項。要使用這些庫，您首先需要將它們添加到您的 Python 項目中。
如果您使用Requests ，則可以使用 Python 的包管理器 pip 安裝它。為此，請打開命令行或終端并運行：
pip install requests對于HTTPx ， pip的安裝命令是：
pip install httpx由于urllib是標準庫的一部分，因此無需單獨安裝它。
然后，在代碼中，您可以導入和使用已添加到項目中的任何庫。例如，如果您使用Requests ，則可以像這樣使用它：
import requests
response = requests.get(‘https://api.com/test-service’)當然，本博客的其余部分將專門關注如何使用Request庫。接下來，讓我們更詳細地了解如何向 API 發出基本請求。
在向 API 發出請求時查看正在運行的代碼是理解上述概念的最簡單方法之一。讓我們使用 Requests 庫演示一個基本的 GET 請求。在下面的示例中，代碼查詢公共 API，然后處理 API 的響應。
import requests
# Replace with the desired API endpoint
url = 'https://api.example.com/data'
response = requests.get(url)
# Checking if the request was successful
if response.status_code == 200:
# Printing the retrieved data
print(response.json())
else:
print(f"Failed to retrieve data: {response.status_code}")在此示例中，我們向 API 端點發送 GET 請求，通過查看狀態代碼（如果請求成功，狀態代碼應為200 ）來檢查請求是否成功，然后打印 JSON 響應。接下來，我們將看一個稍微高級的示例，我們可以通過查詢參數向 API 提供一些數據。
當涉及到開發人員的技能時，查詢參數是構建 API 請求的一個基本方面。查詢參數附加到 API 請求的 URL 中，用于修改請求的行為。本質上，查詢參數充當 API 可用于自定義響應的過濾器或附加指令/數據。
要將查詢參數添加到 API 請求，您需要使用查詢參數語法，該語法需要一個問號 ( ? )，后跟要添加的查詢參數。多個參數由與號 ( & ) 分隔。下面是帶有 2 個查詢參數的 URL 示例。
https://api.example.com/data?parameter1=value1¶meter2=value2在許多場景中，查詢參數對于 API 使用者和開發人員來說都很有用。查詢參數的常見用途包括：
讓我們考慮一個實際示例，其中我們使用 Python 中的 Requests 庫發出帶有查詢參數的 GET 請求。假設我們正在訪問一個提供書籍信息的 API，并且我們希望根據作者和出版年份過濾結果。我們可以使用下面的代碼來過濾出 JK Rowling 于 1997 年撰寫的書籍。
import requests
url = 'https://api.example.com/books'
params = {
'author': 'J.K. Rowling',
'year': 1997
}
response = requests.get(url, params=params)
if response.status_code == 200:
books = response.json()
for book in books:
print(book)
else:
print(f"Error: {response.status_code}")上面的代碼逐行完成以下任務：
requests庫。https://api.example.com/books )。params的字典，其中包含author和year所需的查詢參數。requests.get()函數。這應該可以讓您很好地了解如何在一個非常簡單的示例中將查詢參數與Requests一起使用。當然，根據用例，查詢參數可能或多或少復雜。
現在我們已經介紹了使用查詢參數的基礎知識，我們可以討論一些提示和技巧來涵蓋一些細微差別。讓我們回顧一下下面一些最重要的內容。
%20或替換為+ 。根據 API 期望的編碼類型，這些值可能會有所不同。最簡單的確認方法是查看 API 文檔中的示例，了解應該對哪些字符進行編碼。在繼續之前，讓我們先介紹最后一個更高級的示例?？紤]一個 API，您必須在其中發送項目列表作為查詢參數。 API 可能期望格式以逗號分隔，如下所示：
https://api.example.com/items?ids=123,456,789在 Python 中，您可以按如下方式構造此 API 請求：
item_ids = ['123', '456', '789']
params = {
'ids': ','.join(item_ids)
}
response = requests.get('https://api.example.com/items', params=params)
# Further processing of the response...這里， ','.join(item_ids)從項目 ID 列表中創建一個字符串，以逗號分隔，適合查詢參數。 Python 和其他語言中存在多種方法來輕松創建具有比單值查詢字符串更復雜的值的請求。
正如我們在上面的一些代碼中看到的，當您向 API 發出請求時，它會返回一個狀態代碼。這些狀態代碼是 HTTP 協議的一部分，并在網絡上進行標準化，提供了一種快速了解請求結果的方法。本質上，他們會告訴您您的請求是否成功。特定的狀態代碼也表示錯誤；如果發生錯誤，錯誤類型將反映在返回的狀態碼中。
狀態代碼有多種用途：
盡管 100 到 599 之間存在許多不同的 HTTP 狀態代碼，但有些狀態代碼的使用頻率要高得多。讓我們簡要概述一下您可能會看到的五種最常見的 HTTP 狀態代碼。
正如我們之前提到的，擁有狀態代碼的一個優點是它們可用于通知我們的應用程序應如何處理響應。為了演示如何在 Python 中完成此操作，下面是一個使用 Requests 庫處理不同狀態代碼并相應打印消息的基本示例。
import requests
response = requests.get('https://api.example.com/data')
if response.status_code == 200:
print('Success!')
elif response.status_code == 404:
print('Resource not found.')
elif response.status_code == 500:
print('Server error.')
elif response.status_code == 401:
print('Unauthorized. Authentication required.')
elif response.status_code == 403:
print('Forbidden. Access denied.')
else:
print(f'Error: {response.status_code}')當然，上面的例子非常簡單；它只是將一些內容打印到控制臺。但是，這為更高級的邏輯鋪平了道路，在這些邏輯中，如果返回500狀態代碼，應用程序可能會在 5 分鐘后重試 API 調用，或者如果服務返回401錯誤，則提示用戶輸入某些憑據。
您可以參考詳細的資源和帖子，以更深入地了解狀態代碼的世界及其含義。在 Moesif，我們創建了可以提供幫助的全面指南和解釋以及包含有關狀態代碼的大量信息的其他資源。以下是 Moesif 或其他可靠來源的文章鏈接，供您查看：
這些資源將提供有關所有可能的 HTTP 狀態代碼的更多信息，幫助您在使用 API 時遇到它們時更有效地理解和處理它們。
API 文檔對于開發人員來說至關重要，因為它概述了如何有效地使用 API 并與 API 集成。好的文檔應包括有關 API 端點、請求方法、必要參數和預期響應格式的詳細信息。
通常有兩種類型的 API 文檔：通過 OpenAPI 規范生成的文檔和更典型的手寫 API 文檔。
對于 OpenAPI 生成的文檔，這些文檔利用 OpenAPI（以前稱為 Swagger），這是一種機器可讀 API 文件規范。它允許生成交互式文檔，開發人員可以使用它直接從瀏覽器理解和測試 API。 OpenAPI 生成的文檔通常包括易于導航的界面，其中每個端點的可擴展部分顯示所需的參數、請求示例和響應模型。
更典型的 API 文檔可能在格式上有所不同，但通常包括詳細說明 API 各個方面的綜合指南，例如身份驗證、端點、參數以及示例請求和響應。
讓我們考慮一個假設的示例來了解如何瀏覽 API 文檔。假設我們正在查看天氣 API 的文檔。 /weather端點的部分可能如下所示：
/weathercity （必填）： 城市名稱units ：測量單位（ metric或imperial ）根據以上信息，我們可以構造一個API請求。如果我們想要以公制單位獲取倫敦的天氣數據，我們的請求在 Python 中使用 Requests 庫將如下所示：
import requests
base_url = "https://api.exampleweather.com"
endpoint = "/weather"
parameters = {
'city': 'London',
'units': 'metric'
}
response = requests.get(base_url + endpoint, params=parameters)
if response.status_code == 200:
print(response.json())
else:
print(f"Error: {response.status_code}")然后，此請求將返回包含倫敦天氣詳細信息的響應（該響應將被打印出來），或者調用可能返回錯誤，在這種情況下，我們會將錯誤記錄到屏幕上。
對于更高級的示例，讓我們考慮一個必須設置正文字段的POST請求示例。假設我們有一個用于任務管理器的 API。創建新任務的文檔如下：
/taskstitle （必填）：任務的標題description ：任務的詳細描述將其轉換為請求：
import requests
import json
base_url = "https://api.exampletaskmanager.com"
endpoint = "/tasks"
task_data = {
'title': 'Grocery Shopping',
'description': 'Buy milk, eggs, and bread'
}
response = requests.post(base_url + endpoint, data=json.dumps(task_data))
if response.status_code == 201:
print("Task created successfully:", response.json())
else:
print(f"Error: {response.status_code}")在此 POST 請求中：
json.dumps將task_data字典轉換為 JSON 格式的字符串。requests.post方法發送請求，包括請求正文中的任務數據。盡管 API 文檔的形式和大小各不相同，但在使用 API 文檔來導航新 API 時，需要記住一些關鍵部分。
401響應代碼。如果您使用 RESTful API，您將大量使用 JSON。 JSON（JavaScript 對象表示法）是一種輕量級數據交換格式，易于人類閱讀和編寫，也易于機器解析和生成。 JSON 因其簡單性和靈活性而流行。它與語言無關，解析器適用于每種編程語言，包括 Python。正因為如此，它已成為 API 的通用數據格式。
JSON 對象是鍵值對的集合，其中鍵是字符串，值可以是字符串、數字、布爾值、數組甚至另一個 JSON 對象。下面是 JSON 的示例。
{
"name": "John Doe",
"age": 30,
"isEmployed": true,
"skills": ["Python", "JavaScript", "SQL"]
}Python 內置了json模塊，可用于對 JSON 數據進行編碼和解碼。使用json庫，讓我們看一些如何在 Python 中使用 JSON 的示例
稱為反序列化，下面是如何將 JSON 字符串轉換為 Python 對象的示例。
import json
json_string = '{"name": "John Doe", "age": 30, "isEmployed": true}'
python_dict = json.loads(json_string)
print(python_dict)稱為序??列化，下面是如何將 Python 對象轉換為 JSON 字符串的示例。
python_dict = {'name': 'Jane Doe', 'age': 25, 'isEmployed': False}
json_string = json.dumps(python_dict)
print(json_string)有時，您需要將 JSON 從文件讀取到 Python 程序中。下面是如何使用json.load函數打開文件并加載 JSON 數據的示例。
with open('data.json', 'r') as file:
data = json.load(file)相反，您可能還想將 JSON 數據寫入文件。下面是如何使用json.dump函數執行此操作的示例。
data = {'name': 'Jane Doe', 'age': 25, 'isEmployed': False}
with open('data.json', 'w') as file:
json.dump(data, file)通常，您會收到來自 API 的 JSON 數據作為響應。在這種情況下，您可以使用上述方法來讀取和寫入 JSON（到 API 請求或文件）。下面的示例說明了如何使用response.json讀取 API 中的 JSON 數據，然后將其打印到控制臺。
import requests
import json
response = requests.get('https://api.example.com/data')
# Assuming the response contains JSON data
if response.status_code == 200:
data = response.json() # Converts JSON to a Python dictionary
print(data)
else:
print(f"Failed to retrieve data: {response.status_code}")我們之前介紹過的 Python json模塊為更復雜的 JSON 操作提供了廣泛的支持和功能，例如解析嵌套的 JSON 數據或處理異常。上面的示例應該涵蓋了在 Python 中使用 API 和 JSON 數據時會遇到的許多用例。
現在我們已經介紹了使用 Python 使用 API 的所有基礎知識，您可能還有興趣構建自己的 API。為此，Moesif 創建了一些廣泛的指南，向您展示如何使用Flask和Django （開發人員用來構建 API 的兩個非常流行的 Python 框架）構建 API。
在這些指南中，我們將逐步介紹如何構建您自己的 API，并向您展示如何利用 Moesif 來跟蹤 API 使用情況、錯誤并深入了解用戶行為。查看它們以開始使用 Python 創建您自己的 API。
我們在本博客中介紹了很多內容，從 API 的基礎知識開始，深入研究使用 Python 發出 API 請求、處理 JSON 數據、理解查詢參數和解碼狀態代碼。到目前為止，您應該牢牢掌握如何在 Python 應用程序中使用 API，這是當今互聯數字世界的一項基本技能。
雖然使用 API 至關重要，但創建和管理您自己的 API 可以將您的項目提升到一個新的水平。無論
