成人午夜精品网站在线观看,国产91情侣在线精品国产,一区二区在线观看视频在线

如果無法直接與客戶溝通——可能是因為缺乏接觸、客戶時間有限，或者他們并不清楚自己具體需要什么——那么最好的辦法是站在使用者的角度，想象自己如何使用這個 API，進行大膽而富有創(chuàng)意的思考。盡管不應為了尚未實現(xiàn)的功能設計 API，但從宏觀角度出發(fā)的設計會更有利于將來進行無縫的調(diào)整和改進。例如，下圖展示了 Google Maps 提供的 API，即使沒有深入文檔，僅通過“Autocomplete”或“Address Validation”這些名稱，也可以很清楚地推測其用途和潛在的客戶應用場景。

避免使 API 過于復雜

客戶使用 API 的目的是希望繞過復雜的編程挑戰(zhàn)，以便能夠?qū)Ｗ⒂谒麄兩瞄L的部分。如果使用您的 API 需要學習全新的系統(tǒng)或語言，客戶可能會覺得這不符合他們的需求，從而尋求其他更簡便的解決方案。因此，團隊設計的 API 應既強大又智能，能夠滿足客戶需求，同時也要足夠簡潔，能夠隱藏背后復雜的實現(xiàn)細節(jié)。

例如，如果您知道客戶通過 API 向消費者提供有關最近開業(yè)的餐廳和評價較高的比薩店的信息，那么一個簡單明了的 API 調(diào)用將會非常有幫助，例如：

GET /restaurants?location=Austin&category=Pizzeria&open=true&sort=-priority,created_at

要檢查您的 API 是否足夠簡潔，可以假裝從零開始構(gòu)建整個系統(tǒng)，或者請愿意提供反饋的可信賴客戶進行測試并報告結(jié)果。如果您能夠順利完成整個工作流程，而無需在過程中停下來思考或解決問題，那就說明設計已相當成熟。相反，如果在編碼過程中發(fā)現(xiàn)自己不斷因系統(tǒng)的復雜性而感到困惑，說明還需要進一步優(yōu)化。當能夠確保 API 不會讓用戶感到困惑，并且既能滿足當前需求，又能靈活應對需求變化時，您的 API 就可以準備發(fā)布了。

避免創(chuàng)建過多的“聊天”API

頻繁的網(wǎng)絡調(diào)用會顯著降低系統(tǒng)性能，并增加連接開銷，從而導致更高的運營成本。因此，減少 API 調(diào)用次數(shù)是優(yōu)化 API 設計的一個關鍵因素。

關鍵在于由外而內(nèi)的設計思維：簡化。需要尋找方法，減少客戶在其應用程序中必須執(zhí)行的 API 調(diào)用次數(shù)。例如，如果客戶正在開發(fā)移動應用程序，他們通常需要最大限度地減少網(wǎng)絡流量，以降低電池消耗。在這種情況下，減少從多個調(diào)用到單個調(diào)用的轉(zhuǎn)變，可能對性能和用戶體驗產(chǎn)生顯著影響。

在設計時，不必在構(gòu)建獨特的數(shù)據(jù)驅(qū)動微服務和簡化 API 使用之間做出選擇，理想的做法是同時提供兩者：針對特定數(shù)據(jù)類型的精細 API 和專注于提升用戶體驗的“體驗 API”（Experience API）。這些體驗 API 將多個小型功能整合到一個端點中，從而幫助客戶（尤其是構(gòu)建用戶界面的開發(fā)者）更輕松、快速地展示數(shù)據(jù)。例如，對于常見的用戶界面，您可以提供一個集成了多個數(shù)據(jù)源的 API，讓客戶能夠直接呈現(xiàn)信息，而無需多次調(diào)用。

另一種選擇是使用像 GraphQL 這樣的技術，來實現(xiàn) API 的定制化。雖然通常不建議為每個可能的屏幕構(gòu)建獨立的終端節(jié)點，但像主頁、用戶賬戶信息等常見屏幕的 API 設計，如果能夠合并為一個簡潔的調(diào)用，將大大提高效率，并顯著改善 API 用戶的體驗。

避免限制 API 靈活性

即使遵循了所有設計原則，仍然可能會遇到一些邊緣情況，這些情況不適合當前設計的標準有效負載。可能是某些客戶在單個結(jié)果頁面上需要比平常更多的數(shù)據(jù)，或者返回的數(shù)據(jù)量遠超應用程序的實際需求。在這種情況下，雖然不可能為所有情況提供統(tǒng)一的解決方案，但也不應讓 API 變得過于限制性。為了讓您的 API 更加靈活，以下是三種簡單的改進方法：

1. 篩選響應屬性

可以通過查詢參數(shù)來控制返回的數(shù)據(jù)類型，例如排序和分頁，或者使用像 GraphQL 這樣的技術來實現(xiàn)更加靈活的查詢。讓客戶選擇只請求他們需要的屬性，避免返回過多不必要的數(shù)據(jù)。例如，如果某些客戶只需要書名、作者和暢銷書排名，可以通過查詢參數(shù)僅獲取這些數(shù)據(jù)：

GET /books?fields=title,author,ranking

2. 支持分頁和排序

通常，您可能不希望 API 保證響應中對象的順序，因為數(shù)據(jù)源的微小變化可能會導致排序順序發(fā)生變化。然而，在某些情況下，客戶可能需要按特定字段對數(shù)據(jù)進行排序。提供分頁選項，并允許用戶根據(jù)需求對數(shù)據(jù)進行排序，這樣可以提高 API 的效率。例如，Spotify API 就是通過簡單的 offset 和 limit 參數(shù)來實現(xiàn)分頁，幫助用戶高效獲取數(shù)據(jù)。以下是一個示例：

$ curl https://api.spotify.com/v1/artists/1vCWHaC5f2uS3yhpwWbIA6/albums?album_type=SINGLE&offset=20&limit=10

3. 使用 GraphQL 等技術實現(xiàn)動態(tài)查詢

由于客戶的需求各異，提供動態(tài)數(shù)據(jù)組合的能力可以讓他們根據(jù)具體需求構(gòu)建查詢，而不必局限于固定的數(shù)據(jù)類型或預定義的字段組合。GraphQL 提供了這種靈活性，使客戶能夠按需請求數(shù)據(jù)，避免了構(gòu)建多個不同終端節(jié)點的麻煩。如果不能使用 GraphQL，也可以通過查詢字符串參數(shù)（如 expand）來支持更復雜的查詢。以下是一個示例響應，展示了包含嵌套屬性的公司資源集合：

"data": [

   {

     "CompanyUid": "27e9cf71-fca4",

     "name": "ABCCo",

     "status": "Active",

     "_embedded": {

       "organization": {

         "CompanyUid": "27e9cf71-fca4",

         "name": "ABCCo",

         "type": "Company",

         "taxId": "0123",

         "city": "Portland",

         "notes": ""

       }

     }

   }

]

通過這些改進，您可以在滿足不同需求的同時，保持 API 的靈活性和高效性。

避免讓設計對人類來說不可讀

“KISS”原理（Keep It Simple, Stupid）在 API 設計中尤為重要。雖然 API 是為了計算機間的交互而設計的，但 API 的首要客戶端始終是人類，而 API 協(xié)定本身就是文檔的一部分。開發(fā)人員通常在深入查看文檔之前，會首先關注 API 的有效負載設計。研究表明，開發(fā)人員大約 51% 的時間是在編輯器和客戶端中度過的，約 18% 的時間是在查閱文檔。

例如，下面的有效負載設計需要一些時間來理解，因為其中使用了“id”這一通用字段名，而沒有清晰地描述屬性的意義。即使是“data”這一屬性名，除了 JSON 格式的約定外，并沒有明確表達其具體含義。多加一些字節(jié)，選擇更具描述性的字段名，可以有效避免混淆并加速 API 的采用。以下是一個例子，注意 “user-ids” 在 JSON 結(jié)構(gòu)中的出現(xiàn)，如何讓開發(fā)人員在讀取時產(chǎn)生疑惑：

"{id-a}":

{

  "data":

  [

    {

      "AirportCode": "LAX",

      "AirportName": "Los Angeles",

      "From": "LAX",

      "To": "Austin",

      "departure": "2014-07-15T15:11:25+0000",

      "arrival": "2014-07-15T16:31:25+0000"

    }

  ]

}

這樣的 JSON 設計可能讓開發(fā)人員在理解數(shù)據(jù)時感到困惑。因此，保持有效負載的簡單和直觀是很重要的。如果某些字段名稱可以有多種解釋，最好做出調(diào)整，確保它們一目了然。以下是來自 aviationstack API 的 Airlines 端點響應示例，展示了如何通過清晰、簡潔的字段名，使得數(shù)據(jù)易于理解：

"data": [

   {

     "airline_name": "American Airlines",

     "iata_code": "AA",

     "iata_prefix_accounting": "1",

     "icao_code": "AAL",

     "callsign": "AMERICAN",

     "type": "scheduled",

     "status": "active",

     "fleet_size": "963",

     "fleet_average_age": "10.9",

     "date_founded": "1934",

     "hub_code": "DFW",

     "country_name": "United States",

     "country_iso2": "US"

   },

   [...]

]

可以看到，字段名稱直接反映了數(shù)據(jù)的含義，保持了 JSON 結(jié)構(gòu)的簡單性，同時明確地傳達了預期結(jié)果。這種設計能大大減少開發(fā)人員在理解數(shù)據(jù)時的困惑，提高 API 的易用性。

知道何時可以打破 RESTful 規(guī)則

遵循 RESTful 基礎規(guī)范（例如正確使用 HTTP 動詞、狀態(tài)碼和基于資源的無狀態(tài)接口）能夠讓 API 更加直觀，幫助開發(fā)者避免學習全新的詞匯和規(guī)則。然而，值得注意的是，API 的最終目標是幫助用戶高效地完成任務。如果過于嚴格地遵循 RESTful 設計規(guī)范，可能會影響用戶體驗，導致 API 的使用變得更加復雜，進而偏離其初衷。

在設計 API 時，目標應始終是幫助客戶盡可能快速、輕松地使用數(shù)據(jù)并取得成功。有時，為了提供更加簡潔和優(yōu)雅的接口，可能需要打破一些 RESTful 規(guī)則。關鍵是要確保在 API 設計中保持一致性，并在文檔中清楚標明任何可能偏離標準的設計決策。

例如，在某些情況下，為了優(yōu)化性能或簡化開發(fā)過程，您可能會選擇合并多個資源操作到單一端點，或者在特定場景下使用自定義的 HTTP 方法和狀態(tài)碼。盡管這些設計可能違背傳統(tǒng)的 RESTful 規(guī)則，但如果能顯著提升 API 的易用性并幫助開發(fā)人員更快實現(xiàn)目標，那么這些調(diào)整就是合理的。

總之，雖然遵循 RESTful 規(guī)范是一個良好的起點，但最重要的是始終以客戶的需求為中心，在設計時適時靈活調(diào)整，確保 API 的實用性和高效性。