構建你的長壽命的API第1部分：規範驅動的API開發
構建你的長壽命的API第1部分：規範驅動的API開發
這篇文章是由MuleSoft的Mike Stowe在nginx.conf 2016公布的演示文稿改編的。第一部分重點是規範驅動的API開發。
第二部分討論的最佳實踐。你能夠查看完整的呈現的記錄的
v=G8p4g3yYLBw">YouTube。詳細信息例如以下：
0:00 介紹
1:52 API正在改變世界
2:32 API正在連接一切
3:36 API應該是持久的
4:01 構建一個持久的API的5個步驟
4:38 從長計議
6:03 你的API是契約
6:39 細致想清楚
7:36 誰將使用你的API？
8:40 什麽是你的API的目的？
9:41 列出你的用戶可能須要做什麽
10:53 你正在建立什麽類型的API？
11:43 SOAP vs RPC vs REST
12:34 你理解REST約束嗎？
13:42 大多數API不是RESTful
14:55 為長期構建
15:20 版本號控制是必要的邪惡
17:51 什麽時候須要版本號
18:35 什麽時候不須要版本號
19:54 版本號控制不會導致糟糕的設計
21:12 使用規範驅動開發
22:00 混合方法
23:11 敏捷設計周期
24:36 今天的一些API規範
25:05 RAML長處
27:25 RAML是什麽樣子的？
28:33 規範是 Blueprint
0:00介紹
邁克?斯托：今天我們將談論構建你的長壽命的API。在過去的十年裏，我已經有構建和使用API的機會，同一時候發現了幾個不同的事情。
首先是構建API實際上非常easy。這真的不是那麽難寫的代碼，或者使用框架比方Grape、Rails API、Jersey、Apigility，或者其它的框架。
我意識到的第二件事是。人們並不擅長制作持久的API。讓我問大家一個問題：在這裏有多少人使用了一個API已經被破壞？所以我們都有相同的痛點。
這次談話的重點是，我們怎樣才幹使一個API變得持久，為什麽要變得持久，怎樣處理API的版本號問題，以及我們怎樣可以確保我們構建什麽樣API值得我們的用戶會喜歡。所以從長遠來看。它使得我們不會花費很多其它的錢用於開發或者支持。
我們不打算潛入了大量的代碼。相反。我們將專註於原則。最佳實踐，以及我們怎樣建立一個更有效的方法。
1:52 API正在改變世界
我想公平地說：API正在改變世界。假設你以前使用過智能手機，或者即使你以前開過車。你可能已經使用了API。今天有超過15000公共API 在ProgrammableWeb站點上，它們連接各種各樣的設備，但這僅僅是冰山一角。
假設你想想看，有幾十萬甚至上百萬的API， 連接著mobile apps，以及用於商業用途連接部門機構。
2:32 API正在連接一切
今天，API連接了非常多不同的東西。
顯然，他們正在連接我們的移動應用程序，以及連接我們的企業架構，同一時候也連接我的手機與手表，如Apple Watch和Android手表、眼鏡、汽車、冰箱、恒溫器、家用機器人等等。
想一下，全部的東西正在被 API連接著，這是多麽重要。
想象一下，在你的家裏有家庭安全系統，但最糟糕的事情可能發生：有人闖入你的房子。但警報開始關閉，然後說“須要更新”（它無法通知警察，由於API已過期）。這不是一件好事情。
假設我們了解微服務，我們想要做的最後一件事是部署700微服務。都依賴於一個API，可是這個API被破壞了——我們要回去更新700微服務，它們可能須要又一次進行組成。
3:36 API應該是持久的
為了讓API更好的工作，為了讓物聯網更好工作。為了使微服務更好工作，它們須要的API是持久的。
不僅如此，版本號變動或更改你的API的代價是十分昂貴的。這不僅僅是你去說：“我們要重建我們的API或重構我們的代碼”，也關系到全部用戶或者公司的各部門，由於他們依賴這個API。
4:01構建一個持久的API的5個步驟
值得慶幸的是使用五個簡單的步驟。就能夠構建持久的API。
第一步是擁有一個長期的思維模式。這聽起來像是常識，但非常多人會說：“我們要建立這個API，我們要得到它在那裏，我們得到的反饋。然後我們將版本號控制它“，可是實際上從來沒有這麽工作過。
第二步了解你正在建設什麽。
它似乎也是常識，但大多數API是非持久地開發。沒有真正了解什麽是實際上他們須要構建。第三步利用規範驅動的開發，我們將後面談到。第四步納入最佳實踐。然後反復步驟1到4。
4:38從長計議
你的API是契約。我們忘記了，不像一個敏捷的Web應用程序——我們能夠說，“我們將啟動它。然後我們能夠進行更改“——你不能更改你的API。否則會影響你的用戶，造成他們的系統掛掉。版本號控制也不是解決方式。
我最喜歡的長期思考的理由是。你可能真的存在非常糟糕的長期設計。
你可能會覺得你擅長設計，但讓我問你：你以前看過你的代碼一年後。說：“這是最驚人的事情。我不會改變不論什麽東西？我們真的善於在短期內解決問題，但不是長期的。為了使API設計看起來更加安全，你能夠支付一點點很多其它如今或很多其它更晚。所以你須要考慮事情。
思維模式就是一切。
你不會希望一個團隊走向一場籃球比賽，“我們要輸了。我們會輸。”由於非常可能，他們不會贏。同理，API設計也是這樣。
6:03你的API是契約
你的API是契約。我們常常忘記。當我們做出改變（破壞舊功能）時，我們正在奪去消費者賺錢的能力。
當我們改變我們的API，我們的客戶或我們公司的其它部門必須說：“等等，我不得不停止我做的一切。回去和解決的事情，由於你打破了”。
這意味著他們不會加入新功能，他們不會賺很多其它的錢，他們肯定不會支付你很多其它的錢，由於他們正在努力解決的東西。而不是獲得新的客戶。
6:39細致想清楚
在構建API之前，你必須考慮你的API的每一個方面。這些方面可能看起來像基本問題和常識，但他們錯過了非常多。
你的API是為了誰？你正在建立什麽類型的API？你將怎樣維護你的API？非常多公司都說：“看，我們將要構建一個API，推出它。這就是它。”我回答你。這不是它。你必須維護它。它們將是安全補丁。
你怎樣記錄你的API？你要有一個完整的文檔團隊嗎？你要使用Swagger控制臺嗎？你使用RAML嗎？你將怎樣讓用戶與你的API進行互動？你將怎樣處理諸如身份驗證、配置、限制、安全風險、DDoS攻擊、開發者無意中使用無限循環等小事？你要怎樣管理支持？
這些不必是真正艱難的討論，但你必須有。你的支持方法可能是有一個專門的API支持團隊，或者有project師將提供支持。或有一個社區論壇。或者[你甚至能夠說]“我們真的不是投資在API。所以祝你好運; 假設他們須要支持，他們能夠弄清楚”。
7:36誰將使用你的API？
你的終於用戶是誰？它會是如今的客戶嗎？它會是商業夥伴嗎？第三方服務或開發人員？這是非常重要的回答，由於在你能夠構建之前，你必須了解他們是誰，他們須要什麽。他們須要訪問哪些操作？這意味著從第一天開始涉及你的用戶。
當我開始作為一個網絡開發人員，我是一個菜鳥。我有這個攝影client。她告訴我，“我在尋找一個漂亮的攝影站點。我想要這樣的類型的圖像，這樣的類型的字體。”她給了我的規格。我出去了，我建立了最漂亮的攝影站點，在我看來。我把它送給她，她看著它。說：“這是什麽？你使用深色。我做婚紗攝影，我想要淡色。你使用這個圖像，我想要那個圖像。你使用這樣的字體，我想要那個字體。我把我的心倒入這個站點，但結果是她討厭它。由於我沒有讓她參與設計過程。
我沒有問她。她想要什麽樣子的。 API設計也是這個道理。
8:40你的API的目的是什麽？
在MuleSoft時候，我們處理非常多企業客戶，他們說，“嘿。我們想要一個API。”我們回答，“嗯，這是偉大的。但你的API是什麽？”他們說，“我們將與世界分享我們的服務和數據。“所以我們問他們，”好吧，但他們想要什麽數據？他們將要訪問什麽服務？他們將怎樣與你現有的服務或其它API進行交互？他們怎樣與來自第三方的其它API或服務進行交互。他們可能須要與你的服務一起使用？他們須要什麽行動來處理？
一個我們碰到的陷阱是說。“我們要建立的REST API。我們要做的CRUD，我們要做的HTTP方法。”我們開始思考POST，PUT，PATCH，DELETE立即。
退一步說。“他們（我們的客戶）須要可以加入用戶。編輯用戶。可能檢索password。發送消息”。
這下一點是為房間裏的project師。由於讓我們老實說，我們是可怕的：僅僅做必要的。不要喜歡你的API。
9:41列出你的用戶須要做什麽
這是一個很easy的方法來組織一個API。我們僅僅是說。“我們要實用戶，然後你就行創建一個用戶。編輯用戶等等。
我們將有一個消息系統; 這裏是我們的消息。和我們須要的行動。
我們將有產品，所以我們須要可以審查一個產品。加入一個產品到購物車。我們要有一個購物車，所以我們須要建立一個結帳。
當我們經歷這個過程。一些事情開始發生。你註意到的第一件事是，我們已經定義了我們的資源，甚至沒有嘗試。我們有一切為用戶的東西，這是用戶的資源。
全部這些東西的消息[是]的信息資源。
你會註意到的還有一件事是，我們有反復。我們有信息的用戶。並發送一條消息。那麽，它可能沒有不論什麽意義實際上有一個專門的資源下，用戶發送一條消息，這似乎多余。
我們所做的是有機會來看看這個問題，“哪裏不屬於？”我們能夠說。“ 發送消息和郵件用戶在所屬的消息 ”。並且還開發這些兩者之間的關系紐帶。所以。不要回頭說，“讓我們創建一個超媒體地圖並將全部這些事情聯系在一起”事實之後。我們已經創建了一個超媒體地圖。我們已經知道，當我們拉起一個用戶時。我們須要向他們發送消息的能力，這將是一個鏈接。
10:53你正在建立什麽類型的API？
你正在建立什麽類型的API？你要構建一個REST API，一個部分REST API，SOAP，RPC？讓我問你：什麽是正確的類型的API構建？答案是：它取決於它的依賴。
非常多人會說“REST！
”假設你是一個大型企業，而且全部的客戶都是傳統客戶，他們沒有準備好REST API。但他們須要SOAP，由於他們有SOAP庫，它可能使感覺使用SOAP。
這就是為什麽Salesforce最長時間維護SOAP API和REST API。由於這是他們的客戶要求。
為什麽要以該格式構建API？你理解你選擇的格式的優缺點嗎？對你的開發時間意味著什麽？對用戶的可用性意味著什麽？長壽是什麽意思？它將怎樣影響你長期？
11:43 SOAP vs RPC vs REST
對於SOAP。我們能夠說，“哦，SOAP，這是過時了。這是這個龐大的SOAP封裝須要SOAP庫。它僅僅是XML。“可是SOAP有WSDL，當中有些人喜歡，它能夠是狀態或無狀態，這是一種不錯的。
RPC，在還有一方面，是真的，真的好用。它返回統一格式- JSON-RPC或XML-RPC -但真的沒有上線管道得到它。我把這個網址，我得到這個回來，並做了GET或者POST，這就是它。
最後還有REST。它具有全部這些巨大的利益，但有一些註意事項用它。這對於開發者來說也有點難度，特別是當你開始整合超媒體等東西時。由於對鏈接進行硬編碼總是比實際動態使用更easy。
12:34你了解REST約束嗎？
如果你要構建REST API。由於你的目標是實現長久，靈活和敏捷。你真的明確什麽是REST嗎？你是否明確client和server必須可以單獨演進，你對移動設備所做的更改不應該影響server，或者client不應該影響server？
你明確REST是無狀態的嗎？你不在server端存儲狀態。當然，client能夠存儲狀態。可是你不保留他們正在做的調用的記錄。
所以假設我在這裏連續兩個電話，你不記得第一個電話。你不在乎第一個電話。
你自己接受每一個電話。
它是可緩存的。這意味著你不僅在你的最後提供緩存，但你告訴你的用戶，“這裏是怎樣緩存此頁面”或“這裏是你能夠做什麽緩存此頁面，這裏的時間限制”或 ”這將被緩存在全部層”。
13:42大多數API不是RESTful
創建REST理論的Roy Fielding註意到有一天沒有人使用超媒體。他繼續問：“有手冊壞了嗎？文檔是否錯誤？我做錯了什麽，使它不清楚。假設它沒有超媒體。它不是REST？
這是否意味著你必須構建一個完整的。全然RESTful API？絕對不。
你必須構建滿足你需求的API，可是你須要了解為什麽。
有一個公司正在構建一個API的樣例，他們說。“我們要構建REST。
”他們開始使用它，然後隨著時間的推進，非常快他們說，“嗯，我們將讓他們給我們發送HTML，然後我們將發送他們的JSON。”然後是，“我們要做POST，但他們將通過查詢字符串發送數據。
他們開始調整事情，由於他們覺得。“這將使事情更easy和更好的為我們的用戶”。沒有理解他們正在須要什麽的構建API。
他們實際上創建了很多其它的問題。須要很多其它的叠代，並花了非常多錢試圖構建這個API。
再次，了解為什麽要構建一種類型的API而不是還有一種。假設你不這麽做，你將付出很多其它的道路，終於有一個API是一種混合了全部的東西，是不會工作。
14:55為長期構建
這也意味著構建你的API超越今天。這是我們遇到的挑戰。今天我們說。“這是API，這些是我們須要的，這是我們的平臺”。
這是偉大的。但你的平臺二年後將是什麽樣呢？三年？五年？
我們真的，真的非常好的短期設計。但正如Roy Fielding所說，我們對長期設計感到恐懼。
15:20版本號化是一個必要的邪惡
這使我們進行版本號控制。版本號化是一個必要的邪惡。在短期內。非常easy說“我們要版本號。它會是偉大的”。同一時候，版本號也有缺點。
首先，版本號控制會產生向後兼容性，這意味著當你升級API時。依賴於你的API的應用程序將會斷開。當它們遭到破壞，你會聽到投訴。
第二是有多個服務須要維護和多個系統須要支持。你能夠說，“不，不，不 —— 這不是它的工作原理。我們將棄用這個API。我們不會再支持它了。我們要公布一個新的API”。
嗯，這聽起來非常大的理論。直到有一個安全風險，你必須修補這個安全漏洞。
或者你得到那個一百萬美元的客戶說：“你知道嗎？實際上。我們堅持使用舊的API，我們不能升級，我們須要這個功能“或者公司的還有一個部門說”我們須要它”。
在MuleSoft之前，我有機會作為Constant Contact的開發人員傳道人，我的整個工作是讓人們從版本號1升級到版本號2。在這一年我在那裏，我得到了，我想四人升級他們的API。
他們覺得。“這一個工作。
為什麽我們應該回去花錢來解決沒有被破壞的東西？
還有一個問題是版本號控制在開發者之間造成混亂。
在Constant Contact，有一天我打電話，那個行上的紳士說：“我有一個問題：API不工作。”我問他：“你使用什麽版本號的API？”他說，你的。
好吧，沒問題。有時人們會困惑他們使用的是哪個版本號。所以我挖的更深，“它是怎樣工作的？”他回答說：“嗯。我送POST，我得到的數據了。”我說：“好吧。你得到的XML或JSON？”他回答：“是的“。事實證明，他接管了還有一個剛剛說“這沒有成功”的開發者。他呼籲找出為什麽它不工作，但他沒有做家庭作業，他不知道我們使用什麽版本號的API。
它花了大約20分鐘僅僅是要弄清楚他是什麽版本號。
原來他是在版本號2，但他須要的功能是版本號1。這真的把他氣壞啦。由於他們剛剛從版本號1升級到版本號2。
因此。開發者的採用差點兒是不可能的; 你終於會造成混亂，不得不支持新的和舊的API。
17:51什麽時候你須要版本號
當你具有向後不兼容的平臺更改時，你須要對API進行版本號化。
在這樣的情況下。更改API以反映你如今正在做的新事物可能是有意義的。
或者，假設你曾經是一家汽車店，如今你是一家面包店。更改你的API是有意義的。
第二個實例是當你的API不再可擴展時。換句話說。你搞砸了。
你覺得你有完美的API，但你不斷變化和擴展，不斷變化和改進，然後你被卡住，如今你有麻煩。
最後，假設你的規格是過時的。或許[你的客戶]如今想要JSON，但你仍然使用SOAP與XML，所以你須要更新你的API。
18:35什麽時候不須要版本號
你不應該由於你加入新的端點或在響應中加入了其它數據而對API進行版本號化。有關於嚴格模式的論點。除非你正在做一些須要嚴格模式的事情。否則我會避免說“這是數據響應的嚴格模式”。
你不應該版本號，由於你改變了技術（你從Java到Ruby）。
或者假設你更改了應用程序服務。你應該可以更改代碼。你應該可以更改你的服務。你應該可以更改依賴關系。而不會影響API的接口。
這是我們看到的還有一個挑戰。順便說一句。公司說“你能夠基於你的數據庫生成一個API。
我們將依據你的數據庫名稱創建API“。假設你創建一個獨特的接口，那麽實際上是能夠的 -——假設你回去，你開始改變全部這些，並將它從數據庫中解耦。
問題是。一旦你說“好吧，我們使用這個數據庫。我們將移動到CRM“。
全部這些名稱都是嚴格對齊到數據庫。
。
相同的事情，假設你說“看，我們要有一個CRM，我們將通過我們的系統代表一個CRM。
”假設你使用特定的API或特定的系統和你的API的頂部緊密耦合，第二個你改變它們，破壞接口，這是打破了向後兼容性。
19:54版本號控制不會導致糟糕的設計
版本號控制不能原諒可憐的設計。這很，很重要的須要指出：版本號控制不是一個解決方式。它實際上可能在路上產生很多其它的問題。
設計不佳的API將花費你遠遠，遠遠長於短期內可能給你帶來的優點。
我不自豪的一個故事是我有機會增加MuleSoft作為承包商工作，我們建立了這個API。我們花了六個月的時間編寫代碼，我們構建了這個完美的API。
它遵循全部最佳做法和最新標準; 代碼是完美的。
然後經過六個月的工作，我們公布了這個API，三個星期後。我們意識到沒有人使用它。
這是由於它不是最佳實踐 ——我們有一個偉大的基於REST的API。這僅僅是由於它不能滿足他們的須要。
我們花了接下來的三個月試圖拯救這個API，試圖解決它。可是我們最終最終把它扔掉了。
這是9到10個月的工作全然被拋棄，由於我們的API不能滿足我們的客戶的需求。全部由於我們沒有花兩個星期在開始問我們的用戶。我們沒有涉及我們的用戶，了解他們的需求。
21:12使用規範驅動的開發
我們可以避免的方法是使用一種叫做規範驅動開發。
規範驅動開發的工作方式是我們首先要做的是在我們編寫不論什麽代碼之前定義我們的API。我們還將引入設計模式和代碼重用。我們對全部的應用程序這樣做，所以為什麽我們不使用我們的API設計？
我們將模擬我們的API，並在我們編寫單行代碼之前獲取用戶的反饋。我們進行必要的更改。然後我們開始編碼到規範，而不是偏離。我們的規範成為真理的源泉。
我們終於得到的是一個兩階段的敏捷過程。我們有一個敏捷設計過程來開發契約。然後是一個敏捷開發過程。你能夠使用測試驅動開發來實際開發代碼。
這樣做的原因是，這樣的方式沒有進入代碼或設計，我們沒有測試。我們不確定。
22:00混合方法
所以首先我們要設計我們的API，模擬它。獲得用戶反饋。進行不論什麽更改。測試它，確保它是完美的，然後我們將進入開發。
假設你遇到一個問題在開發中。你[實現]這是一個好主意在理論上。但它不工作會發生什麽？你僅僅需回到設計過程。在你的測試中解決它。確保它的工作，測試它與用戶，然後向前。你如今正在做的是創建一個API，不僅你的用戶會喜歡，這將滿足他們的需求。你要測試現實世界的用例，並且沒有設計缺陷。
假設你不這樣做。會發生什麽？有一個社交媒體巨頭的API，他們有一個資源。假設你想按年齡搜索。你必須把年齡在JSON中的一種方式。假設你想按位置搜索，這是一個全然不同的方式。
假設你想按年齡和位置搜索。它是第三種方式。
這不是由於某些依賴關系。
這是由於他們有不同的開發人員工作，他們沒有意識到，他們有這個設置。
23:11敏捷設計周期
敏捷設計周期是什麽樣的？設計API。在你模擬它後獲取用戶反饋。驗證：“這是否滿足我們的需求？它滿足我們用戶的需求嗎？它是一個好的設計嗎？“假設不是。繼續工作，直到你的設計完好，然後當你準備好。進入編碼階段。
這裏的目標是讓我們的開發者無所畏懼地發展。我們不想讓我們的開發者看看API。而且說“我們正在構建這個資源。並有你的問題。你是怎樣設置這些數據的？你使用駱駝盒還是蛇盒？你使用一個PUT或一個PATCH來處理？數據是否包括在數據對象中？我們怎樣區分這一點？“你不想遇到這些問題。
你不想要這些不一致，由於這些將導致你的API中斷。
這些問題花費代價是很昂貴的。我們說：“嘿，我們要構建這個API。我們要做的MVC，去更改代碼。“和[發現]這是行不通的。好消息是今天，有幾個新的規格，將使這很，很easy。還有一個很好的事情是這些同樣的規格處理了你有很多其它的選擇。所以。你不僅僅是在設計你的API，然後扔那了，就像我們做的瀑布 [發展]。
如今你有一個規範，能夠用來生成你的文檔。能夠用來生成你的測試驅動開發測試。你有一個規範，能夠用來創建SDK和client生成器。交互式場景，全部這些不同的東西。
24:36今天的一些API規範
首先是RAML這是基於REST的API建模語言。
第二個是IO Docs是由Mashery?。
這是我在I / O文檔上的免責聲明：我不會建議使用它，僅僅是由於TIBCO Mashery已經移向Swagger。所以他們真的不是維護I / O文檔了。
第三個是Swagger或OpenAPI Initiative，這是還有一個偉大的和很受歡迎的規格在那裏。
第四個 是API Blueprint。當涉及到的文檔這是夢幻般的。同一時候它有一些偉大的工具。
25:05 RAML長處
我是RAML的粉絲的幾個理由。使用RAML，你能夠在幾行文本中定義API。你能夠看到你的API的樣子。與API設計相比較。
你能夠高速為你的API設計原型，供開發者試用。這意味著，通過點擊button。你能夠將此API發送到世界各地，並讓你的開發者實時地嘗試。
當你發現設計缺陷時，你能夠高速做出調整和更改。
你能夠輕松地記錄你的API。你能夠讓開發者在線試用你的API。
RAML還有一大特點是一種叫做API Notebook。
而不是讓你的開發商說[給你的客戶]。“嘿，這裏是我們的API。你覺得什麽？“你能夠發送給你的客戶一個API Notebook，而且不須要編寫不論什麽小代碼之外的代碼，他們實際上能夠測試你的API使用真實的用例。看看它是否滿足他們的需求。
你能夠讓開發者在線試用你的API。
你能夠讓開發者通過API Notebook與其它API交互。然後，假設你想要SDK，client生成器，代碼封裝器、庫、甚至你的構建API的框架。你能夠通過開源社區生成這些。假設你正在為大眾消費的SDK，可是。我真的會傾向於使用專業的公司像瘦APIMatic.io或REST United，由於不管你使用RAML或Swagger，非常多開源的client生成器是一種粗略。
最重要的是，這是我更喜歡RAML超過Swagger的真正原因——你能夠使用數據模型和設計模式。這意味著我們說“這些API看起來是我們想要的”。
你能夠重用代碼; 你能夠拉入庫，這意味著假設你有一個用戶對象跨多個API共享，你能夠以命名空間的方式拉。
你能夠創建疊加層，因此你能夠有一個規範，然後能夠覆蓋你的開發環境，你的QA環境。預發和生產[環境]等。
在這個樣例中。我們希望有一個資源類型collection。對於我們的集合，我們將一次獲得多個項目。
我們get有一個樣例說明。
而不是一次重新地寫了這一切。我們不得不說exampleCollection。在為我們拉取Rest。
27:25 RAML是什麽樣子？
RAML是什麽樣子的？這是我為什麽我喜歡RAML，順便說一句。
RAML很具體，很復雜[不！
]。
假設我想創建一個資源，我想打電話給一個資源播放列表，我將怎樣定義在RAML文件中？/playlists，就像我在API上。假設我想加入一個GET到方式播放列表，我怎麽想補充一點？get。假設我想有一個200反應，是什麽狀態代碼我用它來把一個200回應？200。
所以，你能夠看到它非常easy開始使用。RAML的優點在於，假設你是一個開發者。一個科技作家。或者CEO，無關緊要。你甚至能夠讓你的CEO改動你的API文檔; 這取決於你。我不會去過多的深入RAML。但你想深入了解到很多其它請看raml.org。因此，總的來說。在構建API時，你將須要使用規範，不管是RAML還是Swagger。
28:33規範是Blueprint
但記住它不是一個“完畢”。
一旦開始設計API，每次進行更改時。都要運行這些測試。這樣做的原因是，你能夠設計完美的基礎，但假設你開始不對地構建在它的頂部。你縮短你的壽命。
這篇文章是由MuleSoft的Mike Stowe在nginx.conf 2016公布的演示文稿改編的。
第一部分重點是規範驅動的API開發。第二部分討論的最佳實踐（請看興許章節）。你能夠查看完整的呈現的記錄的YouTube。
構建你的長壽命的API第1部分：規範驅動的API開發