RAML的全稱是[RESTful API建模語言](http://raml.org/spec.html)，這是一種基于[YAML](http://yaml.org/)格式的新規范，因此機器與人類都能夠輕易地理解其中的內容。但RAML的目的不僅僅在于創建更易于理解的規范（你可以將這一工作指派給文檔團隊，他們會做得更好）而已。RAML的設計者[Uri Sarid](https://twitter.com/usarid)希望使用者能夠打破固有的思維，在開始編寫代碼之前以一種全新的方式對API進行建模。 [TOC] [Roy Fielding](http://roy.gbiv.com/)博士在他的博客[Untangled](http://roy.gbiv.com/untangled/)中指出，現在的人們總有一種傾向，他們只考慮短期的設計，目光只能看到我們所知的、我們目前所想的內容。 REST風格的發明者Roy Fielding表示：“很不幸，人們很善于處理短期的設計，但對于長期的設計通常就束手無策了。” 設計API的一大挑戰在于，API通常都會存在較長的一段時間，有可能會存在數年之久。畢竟，API的設計需要開發者投入大量的精力，但同樣對于客戶來說也是一種極大的投入，因為客戶也依賴于這些API，需要基于它們進行開發。從2009年起，Uri開始思考如何解決API的長期設計的挑戰，他希望能夠找到一種工具，讓設計者只需幾行代碼就能夠對API進行建模（或設計），然后快速地生成一個原型，讓全球的開發者都能夠嘗試你的原型并提供反饋。在2013年，隨著RAML 0.8的發布，他的夢想終于變成了現實。 自那時起，人們對于RAML的興趣就在不斷地升溫。無論是大型企業還是小公司，他們都開始意識到了RAML所帶來的益處：包括以一種人類可讀的格式設計API、在設計時就看到這些API將怎樣工作、并且能夠為API創建一個活動的、全功能的示例，讓開發者能夠簡單地通過點擊按鍵，對這個API發起實際的調用。 [](https://box.kancloud.cn/2015-09-12_55f434c323d71.png) > **提示** > 所有的RAML工具都是開源的，可以從[http://RAML.org/projects](http://raml.org/projects)免費下載。我的雇主MuleSoft還提供了這些工具的免費托管版本，你可以從[AnyPoint Platform for APIs](http://anypoint.mulesoft.com/apiplatform/)平臺試用這些工具。 ## API契約的設計周期 但是，僅僅簡單地創建一個原型是不夠的。MuleSoft創建了一種API契約設計周期圖，這一設計的前提在于API不僅僅是機器之間的一種契約，同樣也是提供商與用戶之間的一種契約。  這也意味著，在設計與創建原型之后，開發API的公司需要找到一種方式以共享他們的API，并從使用者那里獲取反饋。這些有價值的反饋能夠讓公司找到設計中的缺陷，例如數據或結構中的不一致性，以及API中的一些令人困惑之處。在這一階段及時發現設計中的問題非常關鍵，因為一旦你的API發布之后需要修改，那么在大多數情況下都會破壞向后兼容性，而這將影響API的使用。 提示 這一周期同樣也是[規范驅動開發](http://www.mikestowe.com/2014/11/what-is-spec-driven-development.php)（Spec Driven Development）過程的基礎。 ### API Console與API Notebook 為了實現這一設計周期，又出現了兩種工具：即API Console與API Notebook。API Console與其它API控制臺的作用很相似，例如Mashery的[IO Docs](http://www.mashery.com/product/io-docs)與[Swagger](http://swagger.io/)，它提供了一個可進行文檔工作的交互式環境，讓開發者輸入數據和發起調用請求。這意味著開發者在設計API原型的同時，也能夠快速地看到可用的資源與方法，并且立即進行測試，以獲得第一時間的驗證結果。同時，一旦你的API發布之后，除了靜態文檔之外，你也能夠發布交互式的文檔，讓開發者在一個相當簡單的界面中試用這些API，并對API調用進行調試。 另一方面，[API Notebook](http://apinotebook.com/)的交互性與探索性更進一步，它能夠讓開發者使用JavaScript去調用你的（以及其他人的）API。在API Notebook中還能夠對數據進行各種操作，通過實際應用中的用例觀察它的運作。也就是說，開發者能夠通過用例測試他們的原型，所需的只是編寫幾行JavaScript而已。 舉例來說，在下面這張截圖中，用戶能夠連接到[Instagram的API](https://instagram.com/developer/)，通過OAuth進行驗證，并嘗試搜索帶有“kitten”這個標簽的圖片，一步一步完成設計過程。 (點擊放大圖像) [](https://box.kancloud.cn/2015-09-12_55f434c9622be.png) 但作為一個RAML工具，API Notebook真正強大的地方在于你可以為API的使用者創建用例，讓他們自己進行走察。此外，你所創建的用例場景可以用于原型的設計以及發布于生產環境的API，并且你的調用者也能夠通過markdown語法創建自己的Notebook。這樣一來，你的使用者就能夠共享bug與用例的信息，以獲得更好的反饋與支持，并且無需共享任何私有的代碼，也無需走查整個應用程序。 這個特性很簡單，但它卻讓你的使用者不必將大量的精力用于尋找問題的根源，同時也讓你的支持團隊能夠快速地重現這些錯誤，而無需猜測這些問題是否是由客戶端代碼所引起的。 等到你收集了這些反饋之后，就能夠對你的設計進行調整，并決定該設計是否已經可以在生產環境中應用了。它的另一個益處在于，當你的API已經準備好上線時，你就能夠在生產環境中使用這兩個優秀的工具了，正如上文所說的那樣。 為了幫助你的API順利上線，可以在社區中找到許多其它實用的工具，包括用于生成API的相應代碼以及對API進行測試的工具，例如[Abao](https://github.com/cybertk/abao)。除了API Console與the API Notebook之外，還有大量的工具能夠幫助你進行文檔化工作，包括[RAML to HTML](https://github.com/kevinrenskers/raml2html)，它能夠生成一個單一的HTML文件（與API console相類似）作為文檔。以及[使用PHP的RAML2HTML](http://www.mikestowe.com/2014/05/raml-2-html.php)工具，這個腳本能夠創建一個完整的、多頁面的文檔網站： (點擊放大圖像) [](https://box.kancloud.cn/2015-09-12_55f434cbe6a91.png) 這個腳本可以進行充分的自定義，可以修改全局的模板甚至是內容塊，以滿足你對于文檔的需求。 此外，還有許多工具能夠對RAML進行解析，可以將你的API規范整合到你的自定義應用中，而不關心你的應用是用Ruby、PHP、JavaScript、.NET、Python還是Java編寫的。 ## 人類可讀 由于RAML被設計為一種人類可讀的格式，因此通過它開始設計一個全新的API或定義一個現有的API都非常簡單。雖然你可以在任意一種編輯器中創建RAML，但最方便的方式還是使用在線的API設計器，或是專門為[Sublime](https://github.com/mulesoft/raml-sublime-plugin)或[Visual Studio](https://github.com/mulesoft-labs/raml-dotnet-tools)等IDE所設計的插件（兩者都可以在[RAML.org/projects](http://raml.org/projects)中找到），你可以在設計過程中充分利用它們的工具提示、自動完成以及實時校驗功能，這使得整個過程更加簡便。 開始設計時，首先創建一個包含以下內容的RAML文件： ~~~ #%RAML 0.8 title: This is My API baseUri: http://api.domain.com version: 1 ~~~ 在以上代碼中，我們首先聲明這是一個RAML規范，它對應RAML 0.8（版本1很快就會發布了），并聲明API的標題、基本URI、以及這個API的版本號（這個示例中的API是版本1）。 在RAML中聲明資源非常簡單，只需使用/resourceName格式。而添加方法也同樣便捷，只需引用相應的HTTP謂詞即可： ~~~ #%RAML 0.8 title: This is My API baseUri: http://api.domain.com version: 1 /resource1: get: description: This gets the collection of resource1 post: description: This adds a new item to the collection ~~~ RAML讓你能夠定義多種相應，返回不同的狀態碼、頭信息以及響應體。例如： ~~~ #%RAML 0.8 title: This is My API baseUri: http://api.domain.com version: 1 /resource1: get: responses: 200: headers: cache-control: example: | public, no-cache, no-store body: application/json: example: | {"name":"Michael Stowe"} application/xml: example: | <name>Michael Stowe</name> 400: #... 401: #... ~~~ RAML本身還有大量的其它特性，讓你通過schema與參數定義完整的API。它還允許你使用資源嵌套（與Saas中進行CSS嵌套的方法相近）、文件引用（可以引用多個文件，以保持規范的易讀性和易組織性），甚至是變量或屬性的設置，從而在整個規范中保持一致性。 舉例來說，你可以在規范中按以下方式利用這些特性： ~~~ #%RAML 0.8 title: This is My API baseUri: http://api.domain.com version: 1 /resource1: get: responses: 200: body: application/json: schema: | { "type": "object", "$schema": "http://json-schema.org/draft-03/schema", "id": "http://jsonschema.net", "required": true, "properties": { "firstName": { "type": "string", "required": true }, "lastName": { "type": "string", "required": true, "minLength": 3, "maxLength": 36 } } } /sub-resource: get: queryParameters: firstName: description: "the user’s first name" example: John required: true type: string ~~~ ## 對開發者十分友好 RAML的優點不僅在于簡單的格式與豐富的工具，它還能夠讓開發者應用編碼的最佳實踐，例如模式與重用代碼。這不僅能夠極大地減少開發者的工作，還能夠促使API在不同的資源與方法中保持統一性。雖然你總是能夠抽象出一套schema，以保持規范的良好組織，或是通過“!include”命令引入schema、示例與其它RAML代碼片段，但RAML還提供了兩個額外的實用與獨特的模板特性：即traits與resourceTypes。 ### 通過traits定義通用屬性 RAML的traits特性允許你為方法（GET、PUT、POST、PATCH、DELETE等等）定義通用的屬性（或traits），例如它們是否可過濾、可搜索或是可分頁。 在創建trait時，你實際上是創建了一份模板，它能夠通過接受參數為方法提供屬性，只需幾行代碼就能夠完成。同時為你所需的trait提供了最大程度的靈活性與自定義能力： ~~~ traits: -searchable: queryParameters: query: description: | JSON array [{"field1","value1","operator1"},…] <<description> example: | <<example>> /people: get: is: [searchable: {description: "search by location name", example: "[\"firstName\"\,\"Michael\",\"like\"]"}] ~~~ ### 通過ResourceTypes為資源定義模板 此外，與traits相似，resourceTypes也允許你為資源本身創建模板，以此調用通用的方法與響應。打個比方，對于Collection這種資源類型來說，你可能會大量用到POST與GET方法，并且通常會返回200、201或400等狀態碼。只要將它定義為一種resourceType，你就能夠通過兩行代碼就完成調用，而無需為你所創建的每種資源都加入相同的方法與狀態碼。 ~~~ resourceTypes: - collection: description: Collection of available <<resourcePathName>> get: description: Get a list of <<resourcePathName>>. responses: 200: body: application/json: example: | <<responseVariable>> 400: #... 401: #... /people: type: collection: responseVariable: | { "name" : "Michael Stowe", "company" : "MuleSoft", } ~~~ 你甚至可以在resourceTypes中定義可選的方法，只需為該方法加上一個問號（？）即可。這種可選方法只有在定義了該方法的資源中才會被引入，這就為你賦予了更大的靈活性。 提示 RAML允許你創建任意數目的resourceTypes和traits。不過，如果你發現你所定義的resourceTypes超過兩種（collection與item），那么你可能要評估一下你的API，以確保對這些resourceTypes的使用方式是一致的。你可以在[RAML 200教程](http://raml.org/docs-200.html)中了解到更多的知識。 ### 自動生成SDK RAML還可以通過其它工具為開發者節省寶貴的時間與資源，比方說可以通過[APImatic.io](https://apimatic.io/)等提供者為用戶提供自動生成多種語言的SDK的能力。使用APImatic.io無需手動編寫這些SDK，也不必依賴于社區保持它們的更新，它可以讓你簡單的導入RAML規范，隨后生成面向Java、Python、PHP、Ruby、AngularJS、iOS和 Windows等平臺和語言的SDK。 ### 超越代碼 RAML正逐漸成為API規范方面的領頭人之一，與Swagger和API Blueprint并駕齊驅。現如今已有越來越多的API方案提供者支持這一格式了（包括管理與工具等方面）。 為了加快發展的腳步，同時確保規范的完整性，在RAML于2013年問世的同時，一個由API領域驅動的工作小組也一并成立了。該工作小組將負責指正RAML的發展方向，確保它將繼續遵循最佳實踐，并符合業界的需求。目前，該工作小組由來自MuleSoft、AngularJS、Intuit、Airware、PayPal、API Science、Akana和Cisco的代表所組成。 RAML的出現不過一年多的時間，目前1.0版本的工作還在進行之中，新版本的目標是提供更多的功能，并且更好地滿足業界的需求，同時推進API的最佳實踐。當然，它也面臨著一些挑戰，包括如何定義與描述超媒體，這一點在所有的主要規范中都被提及。 ## 如何為克服這些挑戰作出貢獻 開源社區的優點就體現在這里，新的點子總是能夠找到立足之處。每個有志之士都可以通過訪問[RAML.org](http://raml.org/)加入這一項目，并且在[GitHub](https://github.com/raml-org/raml-spec)上貢獻獨創的工具，或是創建規范的分支。畢竟，RAML的強大之處不僅僅在于目前它所實現的部分，即通過一個單一數據源，通過可視化的方式進行API的設計、創建原型、構建、共享以及進行文檔化，而在于它將如何對未來產生持續性的影響。 ## 關于作者  **Michael Stowe****是一位****RAML****的**忠實支持者，他在創建應用方面已有超過10年的經驗，所涉及的領域包括法規實施、非盈利項目、工業，并且加入了多個開源項目。他目前在MuleSoft擔任開發者管理經理，作為工作的一部分，他經常在各種技術型會議上進行RAML以及API設計方面的演講，包括API Con、API Strategy and Design以及API World等等。由Michael所編著的一本關于REST API設計的書籍即將面世。你可以通過@mikegstowe關注他的Twitter，了解他的最新帖子。你也可以通過[http://www.mikestowe.com](http://www.mikestowe.com/)觀看他所做的演講，并了解他的技術思想。 **查看英文原文：**[The Power of RAML](http://www.infoq.com/articles/power-of-raml)