[[322923]]

【51CTO.com快譯】眾所周知，我們設(shè)計(jì)API的目標(biāo)往往是要通過我們的服務(wù)，為用戶提供一定的功能。雖然HTTP和URL資源都允許數(shù)據(jù)流進(jìn)行一定程度的基本交互，但是它們在面對其他特定需求時，往往會讓您的API顯得力不從心。在此，我們以分頁為例，即：如果某個數(shù)據(jù)庫中存放著上百萬篇的文章，那么我們很可能無法在單次響應(yīng)中，將每一篇文章都發(fā)送給客戶。針對此類需求，業(yè)界提出了參數(shù)化(parametrization)的解決方法。

什么是參數(shù)化?

通常而言，參數(shù)化是一種請求配置。在編程語言中，我們可以通過某個函數(shù)來請求對應(yīng)的返回值。如果一個函數(shù)不帶任何參數(shù)，那么我們將無法直接去影響它的返回值。

API也是如此，尤其是那些無狀態(tài)的REST API。畢竟，所有REST的交互都是無狀態(tài)的。也就是說，每個請求都會包含那些方便連接器理解該請求的所有信息，而且它們與之前的任何請求都無關(guān)。

在實(shí)際應(yīng)用中，我們有許多種方法可以向HTTP請求中添加參數(shù)，其中包括：查詢字符串，POST、PUT報文，各種PATCH請求、以及標(biāo)頭(header)。它們各自都有自己的用例和規(guī)則。

那么，添加所有參數(shù)數(shù)據(jù)的最簡單方法，就是將所有內(nèi)容放入報文內(nèi)。在具體應(yīng)用中，每個端點(diǎn)都會用到POST方法，而許多API也會把所有的參數(shù)放置在報文中。長此以往，傳統(tǒng)的API里積累了越來越多的參數(shù)，以致于它們不再適合查詢字符串等操作。顯然，我們應(yīng)當(dāng)避免在設(shè)計(jì)API時此類極端情況的發(fā)生。

添加何種參數(shù)?

就REST而言，作為API查詢語言的GraphQL，為用戶提供了滿足數(shù)據(jù)查詢的運(yùn)行時。那么，我們是否應(yīng)當(dāng)添加那些在HTTP規(guī)范中已經(jīng)標(biāo)準(zhǔn)化的標(biāo)頭字段類來作為參數(shù)(請參見：http://www.rfcreader.com/#rfc2616_line4589)呢?

• 如果使用Accept標(biāo)頭，我們可以定義響應(yīng)所采用的格式或媒體類型。我們既可以使用它來告知API所需要的JSON或XML，又可以使用它來獲取API的版本(請參見：https://www.moesif.com/blog/technical/api-design/Best-Practices-for-Versioning-REST-and-GraphQL-APIs/?utm_source=dzone&utm_medium=paid&utm_campaign=placed%20article&utm_term=rest%20api%20design%20best%20practices%20for%20parameters%20and%20query%20string%20usage)。
• 而如果使用Cache-Control標(biāo)頭，我們則可以防止API發(fā)送帶有no-cache的緩存響應(yīng)，且無需使用查詢字符串作為cache buster(?cb=)。
• 當(dāng)然，授權(quán)也可以被視為一種參數(shù)。根據(jù)API在實(shí)際授權(quán)過程中的詳細(xì)信息，是否通過授權(quán)，來產(chǎn)生不同種類的響應(yīng)。因此，HTTP也為此定義了一個授權(quán)類型的標(biāo)頭(請參見：http://www.rfcreader.com/#rfc2616_line4922)。

在我們了解了各種默認(rèn)標(biāo)頭字段后，下面我們來討論是否應(yīng)該為自己的參數(shù)創(chuàng)建一個自定義的標(biāo)頭字段，或者將其放入URL的查詢字符串中。

何時該使用查詢字符串?

如果我們已獲悉待添加的參數(shù)不屬于默認(rèn)的標(biāo)頭字段，且并不敏感，那么我們就應(yīng)當(dāng)通過查看查詢字符串，以確認(rèn)是否合適。在查詢字符串的時候，有個<isindex>的HTML元素，可被用于向服務(wù)器發(fā)送一些關(guān)鍵字。而服務(wù)器則會據(jù)此做出響應(yīng)，并列出與關(guān)鍵字相匹配的頁面列表。接著，查詢字符串會被重新用于Web表單，以通過GET的請求方式，將數(shù)據(jù)發(fā)送到服務(wù)器處。

因此，查詢字符串的主要用例便是過濾，它會著重過濾搜索和分頁這兩種特殊的情況。有關(guān)此方面的詳細(xì)討論，請參見：https://www.moesif.com/blog/technical/api-design/REST-API-Design-Filtering-Sorting-and-Pagination/?utm_source=dzone&utm_medium=paid&utm_campaign=placed%20article&utm_term=rest%20api%20design%20best%20practices%20for%20parameters%20and%20query%20string%20usage。不過，正如針對Web表單的目的所示，它可以被用于不同類型的參數(shù)。而RESTful API可以將POST或PUT請求與報文一起使用，以實(shí)現(xiàn)將表單數(shù)據(jù)發(fā)送給服務(wù)器。

我們來看一個有關(guān)嵌套表示(nested representation)的參數(shù)示例。默認(rèn)情況下，我們需要返回文章的普通表示形式(plain representation)。當(dāng)我們將?withComments查詢字符串添加到端點(diǎn)時，?withComments會以普通表示形式返回某篇文章的評論，而且僅需要一個請求即可。至于此類參數(shù)是應(yīng)該被放在自定義的標(biāo)頭中，還是查詢字符串里，則主要取決于開發(fā)人員的個人經(jīng)驗(yàn)與偏好。

根據(jù)HTTP的規(guī)范陳述(請參見：http://www.rfcreader.com/#rfc2616_line1761)：標(biāo)頭字段可以被視為函數(shù)的參數(shù)。不過，將查詢字符串添加到URL中會明顯比創(chuàng)建客戶端標(biāo)頭，要更快、更顯著。實(shí)際上，這些字段充當(dāng)了請求修飾符，其語義等同于編程語言在方法調(diào)用中的參數(shù)。

在實(shí)際應(yīng)用中，您會發(fā)現(xiàn)：在所有端點(diǎn)上保持相同的參數(shù)更適合于標(biāo)頭。例如：身份驗(yàn)證令牌可以由每個請求所發(fā)送。而那些高度動態(tài)的參數(shù)(尤其是僅對少數(shù)幾個端點(diǎn)有效的參數(shù))則應(yīng)該被放在查詢字符串中。例如：每個端點(diǎn)的過濾器參數(shù)都會有所不同。

數(shù)組和映射參數(shù)

對于開發(fā)人員而言，他們可能會經(jīng)常碰到的一個問題是：如何處理查詢字符串中的數(shù)組參數(shù)?例如，我們可能碰到需要搜索多個名稱的需求場景。而通常的解決方案是：使用方括號。如下列代碼所示：

不過，HTTP的規(guī)范指出：由IPv6 [RFC3513]或更高版本標(biāo)識的主機(jī)通過將IP方括號(“[”和“]”)來區(qū)分。這是URI語法中唯一允許使用方括號字符的地方。

我們在許多HTTP服務(wù)器和客戶端的實(shí)現(xiàn)場景中，都應(yīng)當(dāng)牢記上述規(guī)范。當(dāng)然，為了簡便起見，我們可以采用“多次使用一個參數(shù)名稱”的另一種解決方案。如下列代碼所示：

該方法雖然有效，但是它會導(dǎo)致開發(fā)人員體驗(yàn)上的下降。通常情況下，客戶端只會使用類似于地圖(map-like)的數(shù)據(jù)結(jié)構(gòu)。而該結(jié)構(gòu)在被添加到URL中之前，會進(jìn)行簡單的字符串轉(zhuǎn)換。而這恰恰會導(dǎo)致后續(xù)的數(shù)值被覆蓋?？梢?，在發(fā)送請求之前，我們需要進(jìn)行更加復(fù)雜的轉(zhuǎn)換。

與此同時，也有人會采用另一種方法：使用“,”字符來分隔數(shù)值，直接在URL中出現(xiàn)未經(jīng)編碼的字符。如下列代碼所示：

而對于那些類似地圖的數(shù)據(jù)結(jié)構(gòu)，我們也可以使用無需編碼的“.”字符。如下列代碼所示：

另外，您還可以對整個查詢字符串進(jìn)行URL編碼(請參見：https://en.wikipedia.org/wiki/Percent-encoding)，以便直接使用任何想要的字符或格式。不過值得一提的是，這同樣也會大幅降低開發(fā)人員的使用體驗(yàn)。

何時不該使用查詢字符串?

在實(shí)際應(yīng)用中，由于查詢字符串往往是URL的一部分。而那些隱藏在客戶端和API之間的攻擊者(如：中間人，MIM)則可以輕而易舉地讀取到我們的URL，因此我們不應(yīng)該簡單地將諸如密碼之類的敏感數(shù)據(jù)，直接放入查詢字符串之中。

雖然大多數(shù)HTTP客戶端在URL中都會允許使用五位數(shù)(five-figure)長度的字符，但是如果我們未能全面設(shè)計(jì)和考慮URL的整體長度，那么開發(fā)人員在調(diào)試此類字符串時，往往也會經(jīng)歷各種繁瑣和不便。

當(dāng)然，由于我們能夠?qū)⑷魏蝺?nèi)容都定義為資源，因此我們有時候完全可以使用POST端點(diǎn)，來進(jìn)行大量參數(shù)的調(diào)用與傳遞，進(jìn)而將報文中的所有數(shù)據(jù)都發(fā)送給API。

可見，為了避免向查詢字符串中那些具有多個參數(shù)的資源發(fā)送GET請求，進(jìn)而導(dǎo)致冗長且不可識別的URL產(chǎn)生，我們可以設(shè)計(jì)出諸如搜索類型的資源，根據(jù)API的需求，來緩存各種計(jì)算的結(jié)果。同時，我們還可以向/searches端點(diǎn)發(fā)布新的請求。而該請求會將我們的搜索相關(guān)配置與參數(shù)保存在報文之中。通過返回一個搜索ID，以便我們使用它來獲取搜索的結(jié)果。

總結(jié)

作為API設(shè)計(jì)人員或架構(gòu)師，我們所追求的優(yōu)秀實(shí)踐，實(shí)際上就是要找出API的最理想使用方式，以及最簡單的實(shí)現(xiàn)用例。綜上所述，我們建議您注意如下兩個方面：

• 從一開始就能夠借助Moesif(人工智能API服務(wù)平臺)之類的服務(wù)，著手分析自身API的使用模式。
• 嵌套式資源雖然可以提高URL的可讀性，但是如果我們嵌套得太多的話，則會導(dǎo)致URL參數(shù)的冗長。因此，如果您發(fā)現(xiàn)自己創(chuàng)建了一個具有超大的查詢字符串端點(diǎn)，那么我建議您最好從其中提取一部分子資源，放置到報文中作為參數(shù)發(fā)送出去。

原文標(biāo)題：REST API Design Best Practices for Parameters and Query String Usage，作者：Kay Ploesser

【51CTO譯稿，合作站點(diǎn)轉(zhuǎn)載請注明原文譯者和出處為51CTO.com】