示範 API 與 SDK 之間的版本相容性開發範例。示範的開發過程,採用 git flow 的方式來進行版本控制,也包含了透過單元測試,同時採用舊版的 client 測試新版的 server, 確保 API 升級時的相容性問題。
C# HTML Batchfile ASP
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Demo.ApiWeb
Demo.Client.ConsoleApp
Demo.Contracts
Demo.SDK.Test
Demo.SDK.TestConsole
Demo.SDK
.gitattributes
.gitignore
Demo.sln
build.cmd
diagram.pptx
readme.md
run-test.cmd
start-test.cmd
start-web.cmd
update-registry.cmd

readme.md

SDK ToDo:

[X] security: api access token

[ ] data transaction

[X] SDK 要能簡化 app 呼叫 api 的程序

貼近使用的 programming language 使用慣例 例如芬頁的機制要用 IEnumerable 包裝

[ ] SDK 要能進行效能優化 (ex: cache)

[X] SDK (client side) interface

確保 app / sdk 的向前相容性。
若 SDK 有新版本,要保證 app 程式,只需更換新版 SDK DLL 即可。 不用修改 app code 就要能繼續使用

[X] API (server side) interface

確保 sdk / api 的向前相容性。 若 server api 有異動,要保證 app 只要更新到支援範圍內的 SDK,都要能正常使用

[ ] API retry 相容性 (safe & idempotent)

(同樣的 API 重複呼叫多次,不會影響結果)

[X] API 必須遵照 HTTP status code

Reference

https://tw.twincl.com/programming/*641y

RESTful API設計的第一步,是充份了解常用的HTTP動詞。一些API設計的選擇容或見人見智,用錯HTTP動詞就不好了。

GET: 讀取資源 (safe & idempotent)
PUT: 替換資源 (idempotent)
DELETE: 刪除資源 (idempotent)
POST: 新增資源;也作為萬用動詞,處理其它要求
PATCH: 更新資源部份內容
HEAD: 類似GET,但只回傳HTTP header (safe & idempotent)
其它還有一些較少用到的,可參考Wikipedia: Hypertext Transfer Protocol
以上「safe」是指該操作不會改變伺服器端的資源狀態(而且結果可以被cache);「idempotent」是指該操作不管做1遍或做n遍,都會得到同樣的資源狀態結果(但不一定得到同樣的回傳值,例如第2次DELETE請求可能回傳404),因此client端可以放心retry。

http://www.restapitutorial.com/lessons/idempotency.html

swagger https://docs.asp.net/en/latest/tutorials/web-api-help-pages-using-swagger.html

ASP.NET Web API 文件產生器 - 使用 Swagger http://kevintsengtw.blogspot.tw/2015/12/aspnet-web-api-swagger.html

ASP.NET WEB API 文件產生器(2) - SWAGGER http://blog.kkbruce.net/2015/04/aspnet-web-api-2-swagger.html#.V_uwBCh96UM

Swashbuckle - Swagger for Web Api 顯示內容的調整 http://kevintsengtw.blogspot.tw/2015/12/swashbuckle-swagger-for-web-api.html

DATA

REFERENCES