RAML簡介

RAML是什麼

Write once. Use many. Creative laziness encouraged

RESTful API Modeling Language (RAML) makes it easy to manage the whole API lifecycle from design to sharing. It’s concise - you only write what you need to define - and reusable. It is machine readable API design that is actually human friendly.

RAML的全稱是RESTful API Modeling Language，這是一種用來描述基于Restful架構的API（設計API）的語言。它的文法規範是基于YAML的新規範，是以機器與人類都能夠輕易地了解其中的内容。

但是，僅僅簡單地建立一個原型是不夠的。MuleSoft建立了一種API契約設計周期圖，這一設計的前提在于API不僅僅是機器之間的一種契約，同樣也是提供商與使用者之間的一種契約。

在API設計後，可以對外提供模拟的API調用，這樣就能從API使用者那得到具體回報。這些有價值的回報能夠讓公司找到設計中的缺陷，例如資料或結構中的不一緻性，以及API中的一些令人困惑之處。在這一階段及時發現設計中的問題非常關鍵，因為一旦你的API釋出之後需要修改，那麼在大多數情況下都會破壞向後相容性，而這将影響API的使用。

這裡就不對RAML的具體文法做說明了，在我的另一篇文章《raml文法簡單介紹》中對文法有相關介紹。

為什麼用RAML

RAML的目的不僅僅在于建立更易于了解的規範（你可以将這一工作指派給文檔團隊，他們會做得更好）而已。RAML的設計者Uri Sarid希望使用者能夠打破固有的思維，在開始編寫代碼之前以一種全新的方式對API進行模組化。

Roy Fielding博士在他的部落格Untangled中指出，現在的人們總有一種傾向，他們隻考慮短期的設計，目光隻能看到我們所知的、我們目前所想的内容。

REST風格的發明者Roy Fielding表示：“很不幸，人們很善于處理短期的設計，但對于長期的設計通常就束手無策了。”

設計API的一大挑戰在于，API通常都會存在較長的一段時間，有可能會存在數年之久。畢竟，API的設計需要開發者投入大量的精力，但同樣對于客戶來說也是一種極大的投入，因為客戶也依賴于這些API，需要基于它們進行開發。從2009年起，Uri開始思考如何解決API的長期設計的挑戰，他希望能夠找到一種工具，讓設計者隻需幾行代碼就能夠對API進行模組化（或設計），然後快速地生成一個原型，讓全球的開發者都能夠嘗試你的原型并提供回報。在2013年，随着RAML 0.8的釋出，他的夢想終于變成了現實。

自那時起，人們對于RAML的興趣就在不斷地升溫。無論是大型企業還是小公司，他們都開始意識到了RAML所帶來的益處：包括以一種人類可讀的格式設計API、在設計時就看到這些API将怎樣工作、并且能夠為API建立一個活動的、全功能的示例，讓開發者能夠簡單地通過點選按鍵，對這個API發起實際的調用。

周邊生态

• DESIGN

  對于基于RAML的API設計，通常使用API Workbench或API Designer作為設計平台。它們都是由mulesoft開發的，前者作為Atom的插件使用，後者是單獨的一個設計平台。

• BUILD

  設計好的API可以由多種方式進行build： NodeJS,JAVA,NET,Python,Mule,IOT

  這裡我隻簡單介我們常用的兩種。對于JAVA來說，通常我們使用RAML for JAX-RS進行build，簡單來說就是把設計好的RAML轉換成JAX-RS規範的java代碼，用于後續的deploy。還有一種是mule的APIkit,它基于anypoint studio進行raml翻譯及build。

• TEST

  我們可以用多數的第三方進行測試，如API Fortress, API Science, Parasoft, Postman, SmartBear。

• Document

  形成API文檔，我們不再需要花大量的時間。運用API Console，RAML to HTML我們即可以根據RAML自動化動态的生成文檔。

• SHARE

  我們可以簡單的根據RESTful API為Java,.NET,PHP,Ruby等主流語言生成SDK，也可以使用API Notebook體驗全新的API互動方式。API Notebook完全改變了開發人員與API互動的方式，讓他們可以使用基本的JavaScript輕松地嘗試調用，操作資料，甚至連接配接到多個API。

Raml提供了全新的RESTful API設計方式，圍繞其周邊衍生出若幹友善快捷的解決方案。無論是從思維、互動性還是效率上來說，它都是api設計上的一次成功的進步