API & SDK Design #4, API 上線前的準備 - Swagger + Azure API Apps

寫到這邊，寫了那麼多 code, 你的 API 總該要上線了吧! 這篇就來探討一下，除了寫好 Code 之外，API 上線還要 注意什麼? API 這種東西不比一般的系統，API 的開發者是 developer, 使用者也是 developer，溝通可以用更有效率 (更宅? XD) 的方法，而不是只能靠傳統的文件~

這篇主題就擺在 API 開發完成後，要上線的考量。包括如何顧好 DX? 如何讓使用你 API 的 developer 有最好的 usability? 另外一個議題，就是如何挑選適合 hosting API service 的服務? 雲端時代就別再自己架設 server 了， 挑選個好的環境可以事倍功半，輕鬆容易就顧好 reliability.

這篇講的東西比較瑣碎，我分三個部分進行:
第一部分: 以需求為主，把我考量的思考過程花點篇幅寫出來。
第二部分: 介紹 swagger 這套 API Framework 以及 tool chain, 靠他來跟其他 developer 聰明的溝通。
第三部分: Hosting 環境的選擇，我會介紹 Azure 上的 API Apps，選用他可以替我們解決那些問題。

2016/11/27 系列文章: .NET + Windows Container, 微服務架構設計 系列文章: API & SDK Design 系列文章: 架構師觀點 API SDK microservice 系列文章 ASP.NET 架構師 Azure API Apps Swagger DX

API & SDK Design #3, API 的向前相容機制

上一篇意外的受歡迎，那麼續集就不富樫了，sample code 準備好就開始動工…

這篇要講向前相容，不知為何我就直覺的聯想到甘道夫對抗炎魔的場景了 XDD，如果你的 API 沒做好這件事，那麼使用你服務的 APP 結果就會…

“You shall NOT pass!”

講完 API / SDK 之間當下的約定，接下來來講講 API 跟 SDK 之間的承諾吧! 當下的約定，會保證當下的 API 跟 SDK 可以搭配運作，然而承諾，則是保證當下的 API 能夠跟過去某個時間以後的所有版本 SDK 都能夠 搭配，這個很考驗架構師的功力了。一個不小心，過去某個不知名的版本就給你出問題了。負責開發維護 API 的人，該怎麼確保這種問題不會 發生?

2016/10/31 系列文章: .NET + Windows Container, 微服務架構設計 系列文章: API & SDK Design 系列文章: 架構師觀點 API SDK microservice 系列文章 ASP.NET 架構師

暌違多年的獎盃 - Microsoft MVP Award Get!

其實拿到這獎項時，我比其他人還意外 XD, 每個人都只跟我說..

什麼!? 我以為你早就是 MVP 了…

哈哈，不論如何，直到 2016/10，我總算拿到這頭銜了 :D

2016/10/25 MVP 自HIGH

API & SDK Design #2, 設計專屬的 SDK

上一篇出來後，才發現，原來不是每個人都清楚 API 跟 SDK 的差別… 接下去之前我就花點篇幅來說明一下。 這個分不清楚的話實在有點囧啊，以前在本機上，這可能幾乎是一樣的東西，但是到了分散式的環境就不是那麼一回事..。

我這系列打算從 上一篇 介紹 client side 如何用 C# 呼叫 Http API 的技巧，延續到如何開發搭配的 SDK 設計， 以及 web api 在正式上線時必須考量的安全、效能、確保介面的相容性，可靠性等等設計。不過當你的 API 要正式 發布給其他人使用時，要面臨的就遠遠不止設計跟開發層面而已，還會有線上維運等問題，這邊我也會介紹一下 Azure 上的 API App Service, 還有 API Management。

範例程式: 請從 GitHub 下載，本篇的內容對應到 dev-SDK 分支

(sorry, 這圖找不到原圖出處, 知道的請通知我，我再補上~)

2016/10/23 系列文章: .NET + Windows Container, 微服務架構設計 系列文章: API & SDK Design 系列文章: 架構師觀點 API SDK 系列文章 ASP.NET 架構師

API & SDK Design #1, 資料分頁的處理方式

(圖片來源: http://hamidarebai.blogspot.tw/2016/09/building-restful-api-with-aspnet-core.html)

這篇算是 “微服務架構” 系列文章的外傳… 所以標題稍微改一下 XD!

上一篇講到 “重構“，不斷的進行重構，直到能夠將模組切割為服務為止。 這篇就接續這個話題，展示一下服務化之後的 API / SDK / APP 之間的關係，以及設計上要顧慮到的細節。我用最常碰到的資料查詢 API 的分頁機制 當作案例來說明這些觀念。資料分頁是個很煩人的東西，不論是在 UI 或是在 API 層面上都是。尤其是 client 端要把 分頁後的資料重新組合起來，就會有越來越多的 義大利麵風格 的 dirty code 被加進來..

這時 SDK 扮演很重要的角色，善用 C# 的 yield return 就能很漂亮的解決這問題。這篇就來示範幾個 API / SDK 的實作技巧 (C#)，之後微服務講到這部份時，可以再回頭參考這篇的內容。

2016/10/10 系列文章: .NET + Windows Container, 微服務架構設計 系列文章: API & SDK Design 系列文章: 架構師觀點 API SDK 系列文章 ASP.NET 架構師 C# yield return