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