構建自定義API - 需要邏輯檢查

我正在爲我們的大規模應用程序編寫我的第一個成熟的API的規劃和早期編碼階段。多年來我已經使用了多個API，但這是我第一次被要求構建一些能夠在此級別上進行程序化交互的東西。構建自定義API - 需要邏輯檢查

我已經做了相當多的研究尋找最佳實踐等，並確定了我的想法將提供一個相當靈活的應答通信系統。

我的問題是：

這是你期望看到的API交互？

我錯過了什麼重要的東西嗎？

說明API的：

我將使用HTTP類型進行通信1協議和用於認證的獨特API密鑰。

我期待這通過SSL連接通過CURL請求。成功（200 OK）的XML響應（速率限制請求）的

實施例：無法XML響應的

<?xml version="1.0" encoding="UTF-8"?> 
<node> 
    <short_message>Request Complete</short_message> 
    <long_message>Rate Limit Status Response</long_message> 
    <response_data> 
     <rate_limit>40</rate_limit> 
     <rate_used>31</rate_used> 
    </response_data> 
</node>

實施例（將在適當的400/500頭被髮送）;

<?xml version="1.0" encoding="UTF-8"?> 
<node> 
    <error_code>1201</error_code> 
    <short_message>API Error</short_message> 
    <long_message>The requested API version (1.5) is invalid</long_message> 
</node>

此外，我設置了錯誤代碼，用於搜索文檔中用於緩解其他開發人員的偏移。請求的合格/不合格將通過適當的HTTP代碼 - 成功（200），錯誤請求（400），找不到方法（404），驗證失敗（403）等等來提供...

我也在使用基於版本的端點，以便任何代碼更改都不需要外部代碼更改。

最後，devs將能夠請求XML，JSON或PHP序列化數組中的所有響應。

我的代碼的內部非常簡單。所有數據都通過POST（可能使用CURL或其他替代方法）傳遞，包括一個唯一的API密鑰。該API密鑰鏈接到系統中的用戶，然後該用戶將允許內部方法執行爲該特定用戶啓用的有限功能集。

我遵循API的「黃金法則」 - 「總是添加，永不刪除」。

那麼......還有什麼我應該考慮的，我錯過了什麼？

來源

2010-02-25 Shane

巴蒂爾，

我假設你的目標是建立一個RESTful API - 是真的嗎？

我的回答只適用於這種假設是正確的 - 我不是在試圖批評你的設計，只是它的RESTfulness。

REST定義了您的設計必須遵守的4個接口約束才能成爲RESTful。您的設計至少違反了其中三個，因此不是RESTful。這本身不一定是壞事，但重要的是你明白你的系統可能沒有你期望的屬性。

我會盡量讓你以下面的簡短答案開始，但請看看http://nordsc.com/ext/classification_of_http_based_apis.html，我在這裏多討論一下這個問題。然後，您或許可以打破這一切到更小的問題，並在回來這裏或訪問Yahoo羣組休息-討論：http://tech.groups.yahoo.com/group/rest-discuss/

現在簡短的話來設計：

你不應該使用自己的迴應但只使用HTTP提供的代碼。你可以自己編寫自己的程序，但這些程序必須是普遍適用的，而不是針對你的應用程序或交互。
您應該使用特定的媒體類型，而不僅僅是application/xml。如果現有的類型都不符合您的需求（或者可以擴展爲這樣做），則可以開發自己的類型。事實上，主要的設計活動應該花在媒體類型上。這是你的域語義生活的地方。
您必須堅持超媒體約束才能真正實現RESTful。這意味着應該爲客戶提供鏈接和/或表單，以發現接下來可以做什麼。

使用上面提到的分類，你API似乎是一個基於HTTP的I型（http://nordsc.com/ext/classification_of_http_based_apis.html#http-type-one）假設你不把行動，你的URI，這將使其RPC URI隧道技術（http://nordsc.com/ext/classification_of_http_based_apis.html#uri-rpc ）

我希望能幫助您實現您的總體目標。

月

來源

2010-02-25 22:21:54

@Jan Algermissen-（+1）哇，非常好的答案 - 今晚我將通過所有這些鏈接工作。您正確地傾向於您提到的基於HTTP的Type I。我試圖讓開發人員儘可能地訪問它，並認爲這將是最好的方法 - 將我的標記從Restful更改爲其他內容。你認爲REST有什麼缺點嗎？我仍然會使用POST over GET來安全地獲取數據。 – Shane 2010-02-25 23:35:12

很高興有幫助。我顯然是支持REST的，但我也明白，學習曲線很高。我認爲只要你知道系統的特性是什麼，你就可以安全地做最符合要求的事情。因此，如果長期維護成本不是您的主要問題，那麼您可能能夠緊密結合。知道這一點很重要。因此我的'桌子'是因爲我覺得人們真的開始對這一切感到困惑:-) 你最後一句我不明白，你能重新說嗎？ – 2010-02-26 00:03:57

我應該擴大一點！我計劃對所有API調用使用SINGLE URL，而不是爲每個方法/函數調用不同的URL。所以你可以打電話給http://www.domain.com/api/execute/，然後把所有必需的信息發佈到該腳本中。其中一個必需的參數是要執行的方法。我希望這更有意義！另外，我希望這不是太不標準，它似乎會使開發更容易，而不必緊跟多個腳本調用。 – Shane 2010-02-26 01:12:43

XML看起來不錯。但要說更多關於內部邏輯，我們需要更多的細節而不僅僅是XML。

來源

2010-02-25 21:43:51 streetparade

@streetparade - 我現在要做一些調整，並擴展這個問題。謝謝！ – Shane 2010-02-25 23:33:30

可以用作示例的最佳API是您編碼的API。使用相同的命名約定和套管。

另外，嘗試使用您的API構建示例應用程序，您很快就會發現它的缺點。

來源

2010-02-25 21:46:22

有幾件事情：

1）把響應頭到不同的地方 - HTTP報頭和RESPONSE_CODE - 肯定會引起混亂。一些開發人員會在一個地方檢查它，另一個在另一個地方。如果您想要使用該路線，請確保HTTP標頭和返回的XML之間的響應代碼相同。

2）您的服務器不必爲每個響應返回API版本。你在線上浪費點數。如果客戶想要特定版本的API，請讓它們在請求中發送它。你不必將它發回給他們。

3）結合response_code和request_status。看看HTTP如何實現：200-299意味着成功。 400-499意味着客戶端是愚蠢的。 500-599意味着服務器被擰緊。

來源

2010-02-25 22:04:27

@Alex - 對版本號的好評 - 我相信我在另一個API中看到了這一點，並認爲這是一個好主意，但是很明顯，它是多餘的。另外，我將使用HTTP代碼而不是SUCCESS/FAILURE，但保留錯誤代碼以幫助記錄API。 – Shane 2010-02-25 23:32:58

您是否考慮過使用版本化的端點？他們可能需要更多的計劃和維護，但您的用戶會喜歡在您決定更改參數/返回值時不必重寫其代碼。

如果您想出一個計劃來棄用舊版本然後刪除舊版本，這應該不會太痛苦。

來源

2010-02-25 22:10:00 jasonbar

@jasonbar - 實際上，我忘了在原始文章中提到，但我也在爲基於版本的端點提供這個原因。謝謝！ – Shane 2010-02-25 23:31:30

如果你真的建立REST服務，可以這樣考慮：

request_status，應該是有利於HTML響應代碼下降（至少200：OK，400：錯誤的請求， 401：未授權，403：禁止和500：內部錯誤），response_code可能需要在您的文檔中找到問題的解釋。
你要提供不同的格式，響應的格式不應該依賴該URL的，但Accept header

來源

2010-02-25 22:53:38 Mathieu

@mathroc - （+1）好的交易，我看到了幾個類似的評論，所以我將放棄response_status來代替HTTP響應代碼 – Shane 2010-02-25 23:30:56

關於你「單一的URL /端點」的想法的 - 記住，與Apache即可起鍋通過URL重寫規則從單個腳本中獲取可能無限數量的URL。這意味着，在您的「端點」腳本的目錄中的正確定義.htaccess文件就可以自動有你的Web服務器「地圖」傳入的請求這樣的，例如：

 
/foo/slice/1234 => /foo/?action=slice&oid=1234 
/foo/dice/3456 => /foo/?action=dice&oid=3456 
/foo/chop/4567 => /foo/?action=chop&oid=4567

這是非常如果您決定要提供「RESTful」URL（並且可以使用HTTP請求模式GET，POST，PUT，DELETE，HEAD），將會很有幫助。

來源

2010-02-28 18:43:42 Peter

構建自定義API - 需要邏輯檢查

回答

相關問題