日韩无码专区无码一级三级片|91人人爱网站中日韩无码电影|厨房大战丰满熟妇|AV高清无码在线免费观看|另类AV日韩少妇熟女|中文日本大黄一级黄色片|色情在线视频免费|亚洲成人特黄a片|黄片wwwav色图欧美|欧亚乱色一区二区三区

RELATEED CONSULTING
相關(guān)咨詢
選擇下列產(chǎn)品馬上在線溝通
服務(wù)時(shí)間：8:30-17:00
你可能遇到了下面的問題
關(guān)閉右側(cè)工具欄

新聞中心

這里有您想知道的互聯(lián)網(wǎng)營銷解決方案
如何更好的設(shè)計(jì)RESTfulAPI

當(dāng)您的數(shù)據(jù)模型已開始穩(wěn)定，您可以為您的網(wǎng)絡(luò)應(yīng)用程序創(chuàng)建公共API。 你意識(shí)到，很難對(duì)你的API進(jìn)行重大更改，一旦它發(fā)布，并希望盡可能得到盡可能多的前面。 現(xiàn)在，互聯(lián)網(wǎng)對(duì)API設(shè)計(jì)的意見有很多。 但是，因?yàn)闆]有一個(gè)廣泛采用的標(biāo)準(zhǔn)在所有情況下都有效，所以你前面有一堆選擇：你應(yīng)該接受什么格式？ 你應(yīng)該如何認(rèn)證？ 你的API是否應(yīng)該版本化？構(gòu)建API是您可以做的最重要的事情之一，以提高您的服務(wù)的價(jià)值。 通過使用API，您的服務(wù)/核心應(yīng)用程序有可能成為其他服務(wù)增長的平臺(tái)。 看看當(dāng)前巨大的科技公司：Facebook，Twitter，谷歌，GitHub，亞馬遜，Netflix …沒有一個(gè)人會(huì)像今天一樣大，如果他們沒有通過API打開他們的數(shù)據(jù)。 事實(shí)上，整個(gè)行業(yè)存在的唯一目的是消費(fèi)由所述平臺(tái)提供的數(shù)據(jù)。

你的API越簡單明了，使用的人就越多。

許多在網(wǎng)絡(luò)上發(fā)現(xiàn)的API設(shè)計(jì)觀點(diǎn)是圍繞主觀的模糊標(biāo)準(zhǔn)解釋的學(xué)術(shù)討論，而不是在現(xiàn)實(shí)世界中有意義的。 我的目標(biāo)是描述一個(gè)為當(dāng)今的Web應(yīng)用程序設(shè)計(jì)的務(wù)實(shí)的API的***實(shí)踐。 我沒有嘗試滿足一個(gè)標(biāo)準(zhǔn)，如果它不覺得正確。 為了幫助指導(dǎo)決策過程，我寫了一些API必須努力達(dá)到的要求：

  • 它應(yīng)該使用Web標(biāo)準(zhǔn)，他們有意義
  • 它應(yīng)該對(duì)開發(fā)人員友好，可以通過瀏覽器地址欄探索
  • 它應(yīng)該簡單，直觀和一致，使采用不僅容易，而且愉快
  • 它應(yīng)該提供足夠的靈活性來支持大部分我們所設(shè)計(jì)的UI
  • 應(yīng)該是有效的，同時(shí)保持與其他要求的平衡

API是開發(fā)人員的UI – 就像任何UI一樣，確保用戶的體驗(yàn)被仔細(xì)考慮是非常重要的！

RESTful API設(shè)計(jì)定義

以下是我將在本文檔中使用的一些重要術(shù)語：

  • Resource：對(duì)象的單個(gè)實(shí)例。 例如，一只動(dòng)物。
  • 集合：對(duì)象的集合。 例如，動(dòng)物。
  • HTTP：用于通過網(wǎng)絡(luò)通信的協(xié)議。
  • Consumer：能夠發(fā)出HTTP請(qǐng)求的客戶端計(jì)算機(jī)應(yīng)用程序。
  • 第三方開發(fā)人員：不是您項(xiàng)目的一部分，但希望使用您的數(shù)據(jù)服務(wù)的開發(fā)人員。
  • 服務(wù)器：可通過網(wǎng)絡(luò)從客戶端訪問的HTTP服務(wù)器/應(yīng)用程序。
  • 端點(diǎn)：服務(wù)器上的API網(wǎng)址，表示資源或整個(gè)集合。
  • 冪等：無邊際效應(yīng)，多次操作得到相同的結(jié)果。
  • 網(wǎng)址區(qū)段：網(wǎng)址中的斜線分隔的信息。

數(shù)據(jù)設(shè)計(jì)和抽象

首先將從你寫的開發(fā)文檔API開始(比如我們可以看到各個(gè)開發(fā)平臺(tái)的暴露出來的API文檔)，您需要決定如何設(shè)計(jì)數(shù)據(jù)，以及您的核心服務(wù)/應(yīng)用程序如何工作。 如果你在做的API是***次開發(fā)，這應(yīng)該很容易。 如果您要將API附加到現(xiàn)有項(xiàng)目，則可能需要提供更多抽象(畢竟是要按照已有的文檔規(guī)范來做)。

有時(shí)，集合可以表示數(shù)據(jù)庫表，資源可以表示該表中的一行。 然而，這不是通常的情況。 事實(shí)上，你的API應(yīng)該盡可能多地抽象出你的數(shù)據(jù)和業(yè)務(wù)邏輯。 非常重要的一點(diǎn)是，如果您不希望使用你的API很難使用，就不要使用任何復(fù)雜的應(yīng)用程序數(shù)據(jù)來為難第三方開發(fā)人員(讓開發(fā)人員覺得還得對(duì)這些數(shù)據(jù)進(jìn)一步處理而浪費(fèi)更多精力)。

還有你的服務(wù)的很多部分，你不應(yīng)該通過API公開。 一個(gè)常見的例子是許多API不允許第三方創(chuàng)建用戶。

設(shè)計(jì)資源請(qǐng)求

當(dāng)然你知道GET和POST請(qǐng)求。當(dāng)您的瀏覽器訪問不同的網(wǎng)頁時(shí)，這兩個(gè)最常用的請(qǐng)求。POST是如此受歡迎，它甚至流行語我們的平常的說話中，即使那些不知道互聯(lián)網(wǎng)如何工作的人也知道他們可以“發(fā)布”的東西在朋友的Facebook上。

有四個(gè)半非常重要的HTTP動(dòng)詞，你需要知道。我說“一半”，因?yàn)镻ATCH動(dòng)詞非常類似于PUT動(dòng)詞，兩個(gè)通常由許多API開發(fā)人員組合。這里是動(dòng)詞，在他們旁邊是他們相關(guān)的數(shù)據(jù)庫調(diào)用（我假設(shè)大多數(shù)人讀這個(gè)知道更多關(guān)于寫入數(shù)據(jù)庫而不是設(shè)計(jì)一個(gè)API）。

  • GET（SELECT）：從服務(wù)器檢索特定資源，或資源列表。
  • POST（CREATE）：在服務(wù)器上創(chuàng)建一個(gè)新的資源。
  • PUT（UPDATE）：更新服務(wù)器上的資源，提供整個(gè)資源。
  • PATCH（UPDATE）：更新服務(wù)器上的資源，僅提供更改的屬性。
  • DELETE（DELETE）：從服務(wù)器刪除資源。

這里有兩個(gè)較少老牌的HTTP動(dòng)詞：

  • HEAD- 檢索有關(guān)資源的元數(shù)據(jù)，例如數(shù)據(jù)的哈?；蛏洗胃聲r(shí)間。
  • OPTIONS- 檢索關(guān)于客戶端被允許對(duì)資源做什么的信息。

一個(gè)好的RESTful API將使用四個(gè)半HTTP動(dòng)詞，允許第三方與其數(shù)據(jù)進(jìn)行交互，并且不會(huì)將動(dòng)作/動(dòng)詞作為URL段。

通常，GET請(qǐng)求可以被緩存（通常是！）在瀏覽器，例如將緩存請(qǐng)求頭用于第二次用戶的POST請(qǐng)求。 HEAD請(qǐng)求基本上是一個(gè)沒有響應(yīng)主體的GET，并且也可以被緩存。

版本控制

無論你正在構(gòu)建什么，無論你事先做了多少規(guī)劃，你的核心應(yīng)用程序總會(huì)改變，你的數(shù)據(jù)關(guān)系總會(huì)改變，屬性添加和從你的資源中刪除。這只是軟件開發(fā)的工作原理，尤其是如果你的項(xiàng)目還活著并被許多人使用（如果你正在構(gòu)建一個(gè)API，情況可能就會(huì)如此）。

記住，API是服務(wù)器和客戶端之間的已發(fā)布約定。如果您更改了服務(wù)器API，這些更改會(huì)破壞向后兼容性，那么你就打破了這個(gè)約定，客戶端又會(huì)要求你重新支持它(誰讓客戶端依然是之前的版本，調(diào)用的還是之前的API)。為了避免這樣的事情，并讓您的客戶端滿意，您需要偶爾引入新版本的API，同時(shí)仍允許訪問舊版本。

注意，如果你只是為你的API添加新的特性，例如資源上的新屬性，或者如果你添加新的端點(diǎn)(比如之前只有查詢，現(xiàn)在增加一個(gè)修改)，你不需要增加您的API版本號(hào)，因?yàn)檫@些更改不會(huì)破壞向后兼容性。當(dāng)然，您將需要更新您的API文檔。

隨著時(shí)間的推移，您可以棄用API的舊版本。棄用某個(gè)功能并不意味著關(guān)閉它或者降低它的質(zhì)量，而是告訴客戶端您的API，舊版本將在特定日期刪除，并且他們應(yīng)該升級(jí)到較新的版本。

一個(gè)好的RESTful API設(shè)計(jì)將跟蹤URL中的版本。另一個(gè)最常見的解決方案是將版本號(hào)放在請(qǐng)求頭中，但在與許多不同的第三方開發(fā)人員合作之后，我可以告訴您，添加這些請(qǐng)求頭信息并不像添加網(wǎng)址細(xì)分那么容易。

分析

跟蹤客戶端使用的API的版本/端點(diǎn)。 這可以像每次請(qǐng)求時(shí)在數(shù)據(jù)庫中增加一個(gè)整數(shù)一樣簡單。 有很多原因跟蹤API Analytics是一個(gè)好主意，例如，最常用的API調(diào)用應(yīng)該是高效的。

為了構(gòu)建第三方開發(fā)者所喜歡的API，最重要的是，當(dāng)您棄用某個(gè)版本的API時(shí)，實(shí)際上可以使用已棄用的API功能與開發(fā)人員聯(lián)系(在兩個(gè)異構(gòu)系統(tǒng)中當(dāng)對(duì)方的開發(fā)人員調(diào)用本服務(wù)時(shí)順帶告知對(duì)方)。 這是提醒他們?cè)跅売门fAPI版本之前升級(jí)的***方法。

第三方開發(fā)者通知的過程可以自動(dòng)化，例如。 每當(dāng)對(duì)一個(gè)已棄用的功能發(fā)出10,000個(gè)請(qǐng)求時(shí)，發(fā)郵件通知開發(fā)人員。

API Root URL

無論你相信與否，您的API的根位置是重要的。當(dāng)開發(fā)人員使用您的API接手舊項(xiàng)目并需要構(gòu)建新功能時(shí)，他們可能根本不知道您有哪些服務(wù)。幸好他們知道客戶端對(duì)外調(diào)用的那些URL列表。重要的是，進(jìn)入您的API的根入口點(diǎn)盡可能簡單，因?yàn)殚L的復(fù)雜URL將顯得令人生畏，并可能使開發(fā)人員直接略過而不會(huì)采用。

這里有兩個(gè)常見的URL根：

  • https://example.org/api/v1/*
  • https://api.cdxwcx.com/v1/*

如果您的應(yīng)用程序龐大，或者您預(yù)計(jì)它會(huì)變得龐大，將API放在自己的子域（例如 api。）上是一個(gè)不錯(cuò)的選擇。這可以允許在路上一些更靈活的可擴(kuò)展性。

如果您預(yù)計(jì)您的API將不會(huì)增長到那么大，或者您想要一個(gè)更簡單的應(yīng)用程序設(shè)置（例如，您希望從同一個(gè)框架托管網(wǎng)站和API），將您的API放置在域根的URL段（例如 / api /）也有效。

將內(nèi)容設(shè)為您的API根目錄是個(gè)好主意。例如，點(diǎn)擊GitHub的API的根會(huì)返回一個(gè)端點(diǎn)列表。就個(gè)人而言，我喜歡使用根網(wǎng)址提供給開發(fā)人員認(rèn)為有用的信息，例如，如何獲取API的開發(fā)人員文檔。

此外，請(qǐng)注意HTTPS前綴。作為一個(gè)好的RESTful API，您必須在HTTPS之后托管您的API(一個(gè)好的RESTful API總是基于HTTPS來發(fā)布的)。

端點(diǎn)

端點(diǎn)是您的API中指向特定資源或資源集合的URL。

如果你正在構(gòu)建一個(gè)虛擬的API來代表幾個(gè)不同的動(dòng)物園，每個(gè)動(dòng)物園包含許多動(dòng)物，員工（可以在多個(gè)動(dòng)物園工作）和跟蹤每個(gè)動(dòng)物的物種，你可能有以下端點(diǎn)：

  • https://api.cdxwcx.com/v1/**zoos**
  • https://api.cdxwcx.com/v1/**animals**
  • https://api.cdxwcx.com/v1/**animal_types**
  • https://api.cdxwcx.com/v1/**employees**

當(dāng)引用每個(gè)端點(diǎn)可以做什么時(shí)，您需要列出有效的HTTP動(dòng)詞和端點(diǎn)組合。例如，這里有一個(gè)半全面的行動(dòng)列表，可以使用我們虛構(gòu)的API執(zhí)行。請(qǐng)注意，我在每個(gè)端點(diǎn)之前都有HTTP動(dòng)詞，因?yàn)檫@是在HTTP請(qǐng)求標(biāo)頭中使用的相同符號(hào)。

  • GET / zoos：列出所有動(dòng)物園（ID和名稱，不要太多細(xì)節(jié)）
  • POST / zoos：創(chuàng)建一個(gè)新的Zoo
  • GET / zoos / ZID：檢索整個(gè)Zoo對(duì)象
  • PUT / zoos / ZID：更新Zoo（整個(gè)對(duì)象）
  • PATCH / zoos / ZID：更新Zoo（部分對(duì)象）
  • DELETE / zoos / ZID：刪除動(dòng)物園
  • GET / zoos / ZID / animals：檢索動(dòng)物列表（ID和名稱）。
  • GET / animals：列出所有動(dòng)物（ID和名稱）。
  • POST / animals：創(chuàng)建一個(gè)新的動(dòng)物
  • GET / animals / AID：檢索動(dòng)物對(duì)象
  • PUT / animals / AID：更新動(dòng)物（整個(gè)對(duì)象）
  • PATCH / animals / AID：更新動(dòng)物（部分對(duì)象）
  • GET / animal_types：檢索所有動(dòng)物類型的列表（ID和名稱）
  • GET / animal_types / ATID：檢索整個(gè)動(dòng)物類型對(duì)象
  • GET / employees：檢索完整的員工列表
  • GET / employees / EID：檢索特定員工
  • GET / zoos / ZID / employees：檢索在此動(dòng)物園工作的員工（ID和名稱）的列表
  • POST / employees：創(chuàng)建一個(gè)新員工
  • POST / zoos / ZID / employees：在特定動(dòng)物園雇用員工
  • DELETE / zoos / ZID / employees / EID：從特定的動(dòng)物園中解雇員工

在上面的列表中，ZID表示Zoo ID，AID表示動(dòng)物ID，EID表示Employee ID，ATID表示動(dòng)物類型ID。在你的文檔中有一個(gè)鍵，你選擇的任何約定是一個(gè)好主意。

為了簡潔，我在上面的示例中省略了常見的API網(wǎng)址前綴。雖然這在通訊期間可能很好，但在實(shí)際的API文檔中，您應(yīng)該始終顯示每個(gè)端點(diǎn)的完整網(wǎng)址（例如GET http://api.cdxwcx.com/v1/animal_type/ATID）。

注意數(shù)據(jù)之間的關(guān)系如何顯示，特別是雇員和動(dòng)物園之間的多對(duì)多關(guān)系。通過添加其他網(wǎng)址細(xì)分，您可以執(zhí)行更具體的互動(dòng)。當(dāng)然，對(duì)于“FIRE(解雇)”沒有HTTP動(dòng)詞，但是通過對(duì)位于Zoo內(nèi)的Employee執(zhí)行DELETE，我們能夠?qū)崿F(xiàn)相同的效果。

過濾器

當(dāng)客戶端請(qǐng)求對(duì)象列表時(shí)，請(qǐng)務(wù)必為它們提供符合所請(qǐng)求條件的每個(gè)對(duì)象的列表。這個(gè)列表可能是巨大的。但是，重要的是不要對(duì)數(shù)據(jù)執(zhí)行任何任意限制。正是這些任意的限制使第三方開發(fā)者很難知道發(fā)生了什么。如果他們請(qǐng)求某個(gè)集合，并迭代結(jié)果，他們從來沒有看到超過100個(gè)結(jié)果，接下來他們就不得不去查找這個(gè)限制條件的出處(提供服務(wù)端沒有問題，就只能是調(diào)用端的問題了)。到底是他們的ORM的bug導(dǎo)致的，還是因?yàn)榫W(wǎng)絡(luò)截?cái)嗔舜髷?shù)據(jù)包？

盡可能減少那些會(huì)影響到第三方開發(fā)者開發(fā)的無謂限制

然而，重要的是，您確實(shí)為客戶端提供了指定某種過濾/結(jié)果限制的能力。這么做最重要的一個(gè)原因是可以最小化網(wǎng)絡(luò)傳輸，客戶端盡快得到結(jié)果。第二個(gè)重要的原因是客戶端可能是懶惰的，如果服務(wù)器可以為他們做過濾和分頁，一切都更好。還有一個(gè)不那么重要的原因，請(qǐng)求資源越少，對(duì)服務(wù)器的一個(gè)很大的好處是，減少了負(fù)載。

過濾主要用于對(duì)資源集合執(zhí)行GET。由于這些是GET請(qǐng)求，因此應(yīng)通過URL傳遞過濾信息。以下是您可能想要添加到API的過濾類型的一些示例：

  • ?limit = 10:減少返回給Consumer的結(jié)果數(shù)（用于分頁）
  • ?offset = 10:向客戶端發(fā)送信息集（用于分頁）
  • ?animal_type_id = 1:過濾符合以下條件的記錄（WHERE animal_type_id = 1）
  • ?sortby = name&order = asc:根據(jù)指定的屬性對(duì)結(jié)果進(jìn)行排序（ORDER BYname ASC）

其中一些過濾可能與端點(diǎn)URLS冗余。例如我之前提到的GET / zoo / ZID / animals。這與GET / animals是一樣的嗎？zoo_id = ZID。為客戶端提供的專用端點(diǎn)將使他們的開發(fā)更輕松，這對(duì)于您預(yù)期他們會(huì)做很多的請(qǐng)求尤其如此。在文檔中，提及這種冗余，以便第三方開發(fā)人員不會(huì)留意是否存在差異。

還有一個(gè)要說的是，每當(dāng)您執(zhí)行數(shù)據(jù)的過濾或排序時(shí)，請(qǐng)確保您列出客戶端可以過濾和排序的列。我們不希望將任何數(shù)據(jù)庫錯(cuò)誤發(fā)送給客戶端！

狀態(tài)碼

作為RESTful API，使用正確的HTTP狀態(tài)代碼非常重要;他們是一個(gè)標(biāo)準(zhǔn)！各種網(wǎng)絡(luò)設(shè)備能夠讀取這些狀態(tài)碼，例如，負(fù)載平衡器可以配置為避免向發(fā)送大量50x錯(cuò)誤的Web服務(wù)器發(fā)送請(qǐng)求。有很多HTTP狀態(tài)代碼可供選擇，但此列表應(yīng)該是一個(gè)很好的起點(diǎn)：

  • 200OK – [GET]
  • 客戶端從服務(wù)器請(qǐng)求數(shù)據(jù)，服務(wù)器為它們找到它（等冪）
  • 201CREATED – [POST / PUT / PATCH]
  • 客戶端提供了服務(wù)器數(shù)據(jù)，并且服務(wù)器創(chuàng)建了一個(gè)資源
  • 204無內(nèi)容 – [刪除]
  • 客戶端要求服務(wù)器刪除資源，并且服務(wù)器將其刪除
  • 400無效請(qǐng)求 – [POST / PUT / PATCH]
  • 客戶端給服務(wù)器的數(shù)據(jù)不良，服務(wù)器沒有做任何事情（冪等）
  • *錯(cuò)誤404 – [] 
    *客戶端引用了一個(gè)不存在的資源或集合，并且服務(wù)器什么也不做（冪等）
  • *500內(nèi)部服務(wù)器錯(cuò)誤 – [] 
    *服務(wù)器遇到錯(cuò)誤，并且客戶端不知道請(qǐng)求是否成功

狀態(tài)碼范圍

1xx范圍保留用于底層HTTP的東西，你很可能永遠(yuǎn)也用不到。

2xx范圍保留用于成功消息，盡可能確保您的服務(wù)器盡可能多地向客戶端發(fā)送這些消息。

3xx范圍保留用于重定向。大多數(shù)API不使用這些請(qǐng)求很多（不像SEO人使用它們那么頻繁），然而，較新的超媒體風(fēng)格API將更多地使用這些請(qǐng)求。

4xx范圍保留用于響應(yīng)客戶端做出的錯(cuò)誤，例如。他們提供不良數(shù)據(jù)或要求不存在的東西。這些請(qǐng)求應(yīng)該是冪等的，而不是更改服務(wù)器的狀態(tài)。

5xx范圍的狀態(tài)碼是保留給服務(wù)器端錯(cuò)誤用的。這些錯(cuò)誤常常是從底層的函數(shù)拋出來的，甚至開發(fā)人員也通常沒法處理，發(fā)送這類狀態(tài)碼的目的以確?？蛻舳双@得某種響應(yīng)。當(dāng)收到5xx響應(yīng)時(shí)，客戶端不可能知道服務(wù)器的狀態(tài)，所以這類狀態(tài)碼是要盡可能的避免。

預(yù)期的返回文檔

當(dāng)使用不同的HTTP動(dòng)詞對(duì)服務(wù)器端點(diǎn)執(zhí)行操作時(shí)，客戶端需要在返回結(jié)果里面拿到一系列的信息。 下面的列表是非常典型的RESTful API：

  • GET / collection：返回資源對(duì)象的列表（數(shù)組）
  • GET / collection / resource：返回單個(gè)Resource對(duì)象
  • POST / collection：返回新創(chuàng)建的Resource對(duì)象
  • PUT / collection / resource：返回完整的Resource對(duì)象
  • PATCH / collection / resource：返回完整的Resource對(duì)象
  • DELETE / collection / resource：返回一個(gè)空文檔

請(qǐng)注意，當(dāng)Consumer創(chuàng)建資源時(shí)，他們通常不知道正在創(chuàng)建的資源的ID（也不知道其他屬性，如創(chuàng)建和修改的時(shí)間戳）（如果適用）。 這些附加屬性與后續(xù)請(qǐng)求一起返回，當(dāng)然作為對(duì)初始POST的響應(yīng)。

###認(rèn)證

大多數(shù)時(shí)候，一個(gè)服務(wù)器想要知道誰正在做哪些請(qǐng)求。當(dāng)然，一些API提供公共用戶(匿名用戶)使用的，但大多數(shù)時(shí)間的工作是代表某人執(zhí)行。

OAuth 2.0提供了一個(gè)很好的方法。對(duì)于每個(gè)請(qǐng)求，您可以確定知道哪個(gè)客戶正在發(fā)出請(qǐng)求，代表他們請(qǐng)求哪個(gè)用戶，并提供一種（大部分）標(biāo)準(zhǔn)化的方式來過期訪問或允許用戶撤消來自客戶端的訪問權(quán)，需要第三方客戶端知道用戶登錄憑據(jù)。

還有OAuth 1.0和xAuth同樣適用這樣的場景。無論您選擇哪種方法，請(qǐng)確保它是常見的，并且有許多不同的庫為您的客戶端可能使用的語言/平臺(tái)編寫的文檔(比如redis提供Java調(diào)用的API)。

我可以誠實(shí)地告訴你，OAuth 1.0a，雖然它是最安全的選項(xiàng)，但是實(shí)現(xiàn)起來很痛苦。建議你選擇一個(gè)替代品。

內(nèi)容類型

目前，最令人興奮的API提供來自RESTful接口的JSON數(shù)據(jù)。這包括Facebook，Twitter，GitHub，你命名。 XML似乎已經(jīng)失去了優(yōu)勢（除了在大型企業(yè)環(huán)境中）。 SOAP，不幸的是，它過時(shí)了，我們真的沒有看到太多的API把HTML作為結(jié)果返回給客戶端（除非你在構(gòu)建一個(gè)爬蟲程序）。

只要你返回給他們有效的數(shù)據(jù)格式，開發(fā)者就可以使用流行的語言和框架進(jìn)行解析。如果你正在構(gòu)建一個(gè)通用的響應(yīng)對(duì)象并使用不同的序列化器，你也可以很容易的提供之前所提到的那些數(shù)據(jù)格式（不包括SOAP）。而你所要做的就是把使用方式放在響應(yīng)數(shù)據(jù)的接收頭里面。

一些API創(chuàng)建者建議向URL（端點(diǎn)之后）添加.json，.xml或.html文件擴(kuò)展名以指定要返回的內(nèi)容類型，但我個(gè)人不喜歡這一點(diǎn)。我真的很喜歡Accept頭（它是內(nèi)置在HTTP規(guī)范），并且我覺得這么做也比較適當(dāng)一些。

超媒體API

超媒體API很可能是RESTful API設(shè)計(jì)的未來。 實(shí)際上是一個(gè)非常好的概念，它回歸到了HTTP和HTML如何運(yùn)作的“本質(zhì)”。

當(dāng)使用非超媒體RESTful API時(shí)，URL端點(diǎn)是服務(wù)器和使用者之間的約定的一部分。這些端點(diǎn)必須由客戶端提前知道，并且更改這些端點(diǎn)意味著客戶端不再能夠按預(yù)期與服務(wù)器通信。你可以先假定這是一個(gè)限制。

現(xiàn)在，API客戶端已經(jīng)不僅僅只有那些創(chuàng)建HTTP請(qǐng)求的用戶代理了。大多數(shù)HTTP請(qǐng)求是由人們通過瀏覽器產(chǎn)生的。人們不會(huì)被哪些預(yù)先定義好的RESTful API端點(diǎn)URL所約束。是什么讓人們變的如此與眾不同？人們可以閱讀內(nèi)容，點(diǎn)擊鏈接，看看有趣的標(biāo)題，一般來說，探索一個(gè)網(wǎng)站，解釋內(nèi)容，去他們想去的地方。即使一個(gè)URL改變，人們也不受影響（除非，他們事先給某個(gè)頁面做了書簽，在這種情況下，他們?nèi)ブ黜摬l(fā)現(xiàn)原來有一條新的路徑可以去往之前的頁面）。

超媒體API概念的工作方式與人類相同。請(qǐng)求API的根返回一個(gè)URL列表，它可能指向每個(gè)信息集合，并以客戶端可以理解的方式描述每個(gè)集合。為每個(gè)資源提供ID并不重要（或必需），只要提供了一個(gè)URL即可。

隨著超媒體API的客戶端爬行鏈接和收集信息，URL在響應(yīng)中始終是***的，并且不需要事先知道作為約定的一部分。如果URL被緩存，并且后續(xù)請(qǐng)求返回404，則客戶端可以簡單地返回到根并再次發(fā)現(xiàn)內(nèi)容。

在檢索集合中的資源列表時(shí)，將返回包含各個(gè)資源的完整URL的屬性。當(dāng)執(zhí)行POST / PATCH / PUT時(shí)，響應(yīng)可以是3xx重定向到完整的資源。

JSON不僅告訴了我們需要定義哪些屬性作為URL，也告訴了我們?nèi)绾螌RL與當(dāng)前文檔關(guān)聯(lián)的語義。正如你猜的那樣，HTML就提供了這樣的信息。我們可能很樂意看到我們的API走完了完整的周期，并回到了處理HTML上來。想一下我們與CSS一起前行了多遠(yuǎn)，有一天我們甚至可能會(huì)看到，API和網(wǎng)站使用完全相同的URL和內(nèi)容是常見的做法。

文檔

老實(shí)說，即便你不能***的遵循指南中的條款，你的API不一定是糟糕的。但是，如果你不為API準(zhǔn)備文檔的話，沒有人會(huì)知道如何使用它，那它真的會(huì)成為一個(gè)糟糕的API。

使您的文檔可用于未經(jīng)身份驗(yàn)證的開發(fā)人員。

不要使用自動(dòng)文檔生成器，或者如果你這樣做，你也要保證自己審閱過并使其具有更好的版式。

不要截?cái)嗍纠?qǐng)求和響應(yīng)正文，要展示完整的東西。在文檔中使用語法高亮指示符。

記錄每個(gè)端點(diǎn)的預(yù)期響應(yīng)代碼和可能的錯(cuò)誤消息，以及導(dǎo)致這些錯(cuò)誤消息可能出現(xiàn)的錯(cuò)誤。

如果您有空閑時(shí)間，請(qǐng)構(gòu)建一個(gè)開發(fā)人員API控制臺(tái)，以便開發(fā)人員可以立即試用您的API。這不像你想象的那么難，開發(fā)者（內(nèi)部和第三方）也會(huì)因此而擁戴你！

確保您的文檔可以打印; CSS是一個(gè)強(qiáng)大的東西;不要害怕在打印文檔時(shí)隱藏側(cè)邊欄。即使沒有人打印過物理副本，你會(huì)驚奇的發(fā)現(xiàn)有多少開發(fā)者喜歡打印到PDF以供離線閱讀。

勘誤：原始的HTTP封包

因?yàn)槲覀兯龅囊磺卸际峭ㄟ^HTTP，我將向你展示一個(gè)HTTP包的剖析。 我經(jīng)常感到驚訝的是，有多少人不知道這些東西是什么樣子的！ 當(dāng)客戶端向服務(wù)器發(fā)送請(qǐng)求時(shí)，它們提供一組鍵/值對(duì)，稱為標(biāo)題，以及兩個(gè)換行符，***是請(qǐng)求體。 這都是在同一個(gè)數(shù)據(jù)包中發(fā)送的。

服務(wù)器然后以所述鍵/值對(duì)格式，用兩個(gè)換行符然后響應(yīng)主體進(jìn)行響應(yīng)。 HTTP是一個(gè)請(qǐng)求/響應(yīng)協(xié)議; 沒有“推送”支持（服務(wù)器向客戶端發(fā)送數(shù)據(jù)未經(jīng)安全），除非您使用不同的協(xié)議，如Websockets。

在設(shè)計(jì)API時(shí)，您應(yīng)該能夠使用允許查看原始HTTP數(shù)據(jù)包的工具。 例如，考慮使用Wireshark。 此外，請(qǐng)確保您使用的框架/ Web服務(wù)器，允許您閱讀和更改盡可能多的這些字段。

Example HTTP Request

POST /v1/animal HTTP/1.1
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24

{   "name": "Gir",   "animal_type": 12 }

Example HTTP Response

HTTP/1.1 200 OK
Date: Wed, 18 Dec 2013 06:08:22 GMT
Content-Type: application/json
Access-Control-Max-Age: 1728000
Cache-Control: no-cache

{   "id": 12,   "created": 1386363036,   "modified": 1386363036,   "name": "Gir",   "animal_type": 12 }

當(dāng)前題目：如何更好的設(shè)計(jì)RESTfulAPI
文章出自：http://www.5511xx.com/article/cohgjjd.html