Web Api 端點設計 與 Oauth

最近一直看這方面的東西，總結以下：

在後續會進行實例demo演示，本篇進行理論詳解。

下篇相關博客：

《Web Api 內部數據思考 和 利用http緩存優化 Api》

《API接口安全增強設計方法》

一 什麼是Web Api ?

     web api 是指 「使用HTTP協議經過網絡調用的API」。API是「Application Programming Interface」的縮寫，是軟件組件的外部接口。也就是說某個軟件集合體，人們能瞭解它的外部功能，但並不知道（也無需知道）其內部的運做細節，爲了從外部調用該功能，須要指定該軟件集合體的調用規範等信息，而這樣的規範就是API。—— web api的設計與開發一書解釋

二 什麼是API端點 ？

　 端點是指用於訪問API的URI，由不一樣的功能而擁有不一樣的端點。以獲取用戶信息爲例，能夠分配以下URI

https：//api.example.com/v1/users/me

三 URL和URI有什麼區別？

     URI，是uniform resource identifier，統一資源標識符，用來惟一的標識一個資源。而URL是uniform resource locator，統一資源定位器，它是一種具體的URI，即URL能夠用來標識一個資源，並且還指明瞭如何locate這個資源。也就是說，URI是以一種抽象的，高層次概念定義統一資源標識，而URL則是具體的資源標識的方式。URL是一種URI。

四 端點的基本設計

1 容易記憶，URI包含的功能一目瞭然

  A） 短小便於輸入的URI

　　  簡單易記，例如：

http：//api.example.com/service/api/search

        這個URI很差的地方在於：

　　1）域名和路徑都包含api，重複 。

　　2）service 表示服務，彷佛可有可無

　　能夠簡寫爲：

http://api.example.com/search

　　固然，能夠添加其餘區別的路徑名

B）能夠讀懂的URI

　　例如：

http：//api.example.com/sv/u

　　sv和u是啥？service和user嗎？

C）沒有大小寫混用的URI

　  在web設計標準一書中，說的是儘可能路徑採用小寫

http://api.example.com/USERS/12345

與下面對比

http://api.example.com/users/12345

　　這方面見仁見智

D）修改方便的URI

　　假設咱們須要獲取某種商品（item），例：

http://api.example.com/v1/items/123456　　

　　能夠看到v1爲版本號，items爲商品，而且能夠知道改變id，能夠獲取到其餘商品

E）不會暴露服務器架構的URI

例如：

http://api.example.com/cgi-bin/get_user.php?user=100

這透露api是由php語言編寫且以CGI的方式運行。這是多餘的，對於外界來講，並不須要關心語言和運行方式。也增長了服務器受攻擊的可能性

F）規則統一的URI

Tips:查詢參數放於路徑中：例：

http：//api.example.com/v1/user/123:(id,name,desc,other)

五 登陸與OAuth2.0

　　官方網站：http://oauth.net/   http://oauth.net/2/

　　權威定義：OAuth is An open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications. 

　　OAuth是一個開放協議，容許用戶讓第三方應用以安全且標準的方式獲取該用戶在某一網站、移動或桌面應用上存儲的私密的資源（如用戶我的信息、照片、視頻、聯繫人列表），而無需將用戶名和密碼提供給第三方應用。

（換句話說，假設帶有用戶註冊功能的在線服務A，對外公開了api，你本身開發了在線服務B，即可以使用在線服務A的用戶，A用戶也無需註冊，便可使用服務B）

　　OAuth 2.0是OAuth協議的下一版本，但不向後兼容OAuth 1.0。 OAuth 2.0關注客戶端開發者的簡易性，同時爲Web應用，桌面應用和手機，和起居室設備提供專門的認證流程。

OAuth容許用戶提供一個令牌，而不是用戶名和密碼來訪問他們存放在特定服務提供者的數據。每個令牌受權一個特定的網站（例如，視頻編輯網站)在特定的時段（例如，接下來的2小時內）內訪問特定的資源（例如僅僅是某一相冊中的視頻）。這樣，OAuth容許用戶受權第三方網站訪問他們存儲在另外的服務提供者上的信息，而不須要分享他們的訪問許可或他們數據的全部內容。

　　新浪微博API目前也使用OAuth 2.0。

　　在OAuth2.0的處理流程，主要分爲如下四個步驟：

　　　　1）獲得受權碼code

　　　　2）獲取access token

　　　　3）經過access token，獲取OpenID

　　　　4）經過access token及OpenID調用API，獲取用戶受權信息

　　上面是流程的大概四個步驟，流程圖爲：

【圖片摘於網絡】

　　第一步：首先直接跳轉至用戶受權地址，即圖示 Request User Url ，提示用戶進行登陸，並給予相關資源受權，獲得惟一的Auth code，這裏注意的是code只有10分鐘的有效期；

　　第二步：獲得受權code後，這一步就是請求access token，經過 圖示 Request access url ，生成獲得數據Token；

　　第三步：經過Access Token請求OpenID，OpenID是用戶在此平臺的惟一標識，經過圖示 Request info url 請求，而後獲得OpenID；

　　第四步：經過第二步獲得的數據Token、第三步獲得的OpenID及相關API，進行請求，獲取用戶受權資源信息。

六  數據格式

　　無疑，json是最流行的數據格式，其次是xml，同時還有jsonp【不推薦使用，最大的問題在於當服務器返回錯誤時沒法正確應對】，那麼如何指定返回數據格式呢？

　　1）使用查詢參數的方法，例：

http://api.example.com/v1/user?format = xml

　　2）使用擴展名的方法，例：

http：//api.example.com/v1/users.json

　　可是此方法並不推薦，靈活性很低

　　3）使用名爲Accept的請求首部來指明所需的數據格式，例如：

GET /v1/users Host : api.example.com Accept : application/json

　　既然第二種不推薦，那麼能夠第一種和第三種結合的方式設計api。

　　未完待續。。。。。。