RAML的強大功能

RAML的全稱是RESTful API建模語言，這是一種基于YAML格式的新規(guī)范，因此機器與人類都能夠輕易地理解其中的內(nèi)容。但RAML的目的不僅僅在于創(chuàng)建更易于理解的規(guī)范（你可以將這一工作指派給文檔團隊，他們會做得更好）而已。RAML的設計者Uri Sarid希望使用者能夠打破固有的思維，在開始編寫代碼之前以一種全新的方式對API進行建模。

Roy Fielding博士在他的博客Untangled中指出，現(xiàn)在的人們總有一種傾向，他們只考慮短期的設計，目光只能看到我們所知的、我們目前所想的內(nèi)容。

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

設計API的一大挑戰(zhàn)在于，API通常都會存在較長的一段時間，有可能會存在數(shù)年之久。畢竟，API的設計需要開發(fā)者投入大量的精力，但同樣對于客戶來說也是一種極大的投入，因為客戶也依賴于這些API，需要基于它們進行開發(fā)。從2009年起，Uri開始思考如何解決API的長期設計的挑戰(zhàn)，他希望能夠找到一種工具，讓設計者只需幾行代碼就能夠?qū)PI進行建模（或設計），然后快速地生成一個原型，讓全球的開發(fā)者都能夠嘗試你的原型并提供反饋。在2013年，隨著RAML 0.8的發(fā)布，他的夢想終于變成了現(xiàn)實。

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

提示

所有的RAML工具都是開源的，可以從http://RAML.org/projects免費下載。我的雇主MuleSoft還提供了這些工具的免費托管版本，你可以從AnyPoint Platform for APIs平臺試用這些工具。

API契約的設計周期

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

這也意味著，在設計與創(chuàng)建原型之后，開發(fā)API的公司需要找到一種方式以共享他們的API，并從使用者那里獲取反饋。這些有價值的反饋能夠讓公司找到設計中的缺陷，例如數(shù)據(jù)或結(jié)構中的不一致性，以及API中的一些令人困惑之處。在這一階段及時發(fā)現(xiàn)設計中的問題非常關鍵，因為一旦你的API發(fā)布之后需要修改，那么在大多數(shù)情況下都會破壞向后兼容性，而這將影響API的使用。

提示

這一周期同樣也是規(guī)范驅(qū)動開發(fā)（Spec Driven Development）過程的基礎。

API Console與API Notebook

為了實現(xiàn)這一設計周期，又出現(xiàn)了兩種工具：即API Console與API Notebook。API Console與其它API控制臺的作用很相似，例如Mashery的IO Docs與Swagger，它提供了一個可進行文檔工作的交互式環(huán)境，讓開發(fā)者輸入數(shù)據(jù)和發(fā)起調(diào)用請求。這意味著開發(fā)者在設計API原型的同時，也能夠快速地看到可用的資源與方法，并且立即進行測試，以獲得第一時間的驗證結(jié)果。同時，一旦你的API發(fā)布之后，除了靜態(tài)文檔之外，你也能夠發(fā)布交互式的文檔，讓開發(fā)者在一個相當簡單的界面中試用這些API，并對API調(diào)用進行調(diào)試。

另一方面，API Notebook的交互性與探索性更進一步，它能夠讓開發(fā)者使用JavaScript去調(diào)用你的（以及其他人的）API。在API Notebook中還能夠?qū)?shù)據(jù)進行各種操作，通過實際應用中的用例觀察它的運作。也就是說，開發(fā)者能夠通過用例測試他們的原型，所需的只是編寫幾行JavaScript而已。

舉例來說，在下面這張截圖中，用戶能夠連接到Instagram的API，通過OAuth進行驗證，并嘗試搜索帶有“kitten”這個標簽的圖片，一步一步完成設計過程。

(點擊放大圖像)

但作為一個RAML工具，API Notebook真正強大的地方在于你可以為API的使用者創(chuàng)建用例，讓他們自己進行走察。此外，你所創(chuàng)建的用例場景可以用于原型的設計以及發(fā)布于生產(chǎn)環(huán)境的API，并且你的調(diào)用者也能夠通過markdown語法創(chuàng)建自己的Notebook。這樣一來，你的使用者就能夠共享bug與用例的信息，以獲得更好的反饋與支持，并且無需共享任何私有的代碼，也無需走查整個應用程序。

這個特性很簡單，但它卻讓你的使用者不必將大量的精力用于尋找問題的根源，同時也讓你的支持團隊能夠快速地重現(xiàn)這些錯誤，而無需猜測這些問題是否是由客戶端代碼所引起的。

等到你收集了這些反饋之后，就能夠?qū)δ愕脑O計進行調(diào)整，并決定該設計是否已經(jīng)可以在生產(chǎn)環(huán)境中應用了。它的另一個益處在于，當你的API已經(jīng)準備好上線時，你就能夠在生產(chǎn)環(huán)境中使用這兩個優(yōu)秀的工具了，正如上文所說的那樣。

為了幫助你的API順利上線，可以在社區(qū)中找到許多其它實用的工具，包括用于生成API的相應代碼以及對API進行測試的工具，例如Abao。除了API Console與the API Notebook之外，還有大量的工具能夠幫助你進行文檔化工作，包括RAML to HTML，它能夠生成一個單一的HTML文件（與API console相類似）作為文檔。以及使用PHP的RAML2HTML工具，這個腳本能夠創(chuàng)建一個完整的、多頁面的文檔網(wǎng)站：

(點擊放大圖像)

這個腳本可以進行充分的自定義，可以修改全局的模板甚至是內(nèi)容塊，以滿足你對于文檔的需求。

此外，還有許多工具能夠?qū)AML進行解析，可以將你的API規(guī)范整合到你的自定義應用中，而不關心你的應用是用Ruby、PHP、JavaScript、.NET、Python還是Java編寫的。

人類可讀

由于RAML被設計為一種人類可讀的格式，因此通過它開始設計一個全新的API或定義一個現(xiàn)有的API都非常簡單。雖然你可以在任意一種編輯器中創(chuàng)建RAML，但最方便的方式還是使用在線的API設計器，或是專門為Sublime或Visual Studio等IDE所設計的插件（兩者都可以在RAML.org/projects中找到），你可以在設計過程中充分利用它們的工具提示、自動完成以及實時校驗功能，這使得整個過程更加簡便。

開始設計時，首先創(chuàng)建一個包含以下內(nèi)容的RAML文件：

#%RAML 0.8
title: This is My API
baseUri: http://api.domain.com
version: 1

在以上代碼中，我們首先聲明這是一個RAML規(guī)范，它對應RAML 0.8（版本1很快就會發(fā)布了），并聲明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讓你能夠定義多種相應，返回不同的狀態(tài)碼、頭信息以及響應體。例如：

#%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與參數(shù)定義完整的API。它還允許你使用資源嵌套（與Saas中進行CSS嵌套的方法相近）、文件引用（可以引用多個文件，以保持規(guī)范的易讀性和易組織性），甚至是變量或?qū)傩缘脑O置，從而在整個規(guī)范中保持一致性。

舉例來說，你可以在規(guī)范中按以下方式利用這些特性：

#%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

對開發(fā)者十分友好

RAML的優(yōu)點不僅在于簡單的格式與豐富的工具，它還能夠讓開發(fā)者應用編碼的最佳實踐，例如模式與重用代碼。這不僅能夠極大地減少開發(fā)者的工作，還能夠促使API在不同的資源與方法中保持統(tǒng)一性。雖然你總是能夠抽象出一套schema，以保持規(guī)范的良好組織，或是通過“!include”命令引入schema、示例與其它RAML代碼片段，但RAML還提供了兩個額外的實用與獨特的模板特性：即traits與resourceTypes。

通過traits定義通用屬性

RAML的traits特性允許你為方法（GET、PUT、POST、PATCH、DELETE等等）定義通用的屬性（或traits），例如它們是否可過濾、可搜索或是可分頁。

在創(chuàng)建trait時，你實際上是創(chuàng)建了一份模板，它能夠通過接受參數(shù)為方法提供屬性，只需幾行代碼就能夠完成。同時為你所需的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也允許你為資源本身創(chuàng)建模板，以此調(diào)用通用的方法與響應。打個比方，對于Collection這種資源類型來說，你可能會大量用到POST與GET方法，并且通常會返回200、201或400等狀態(tài)碼。只要將它定義為一種resourceType，你就能夠通過兩行代碼就完成調(diào)用，而無需為你所創(chuàng)建的每種資源都加入相同的方法與狀態(tài)碼。

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允許你創(chuàng)建任意數(shù)目的resourceTypes和traits。不過，如果你發(fā)現(xiàn)你所定義的resourceTypes超過兩種（collection與item），那么你可能要評估一下你的API，以確保對這些resourceTypes的使用方式是一致的。你可以在RAML 200教程中了解到更多的知識。

自動生成SDK

RAML還可以通過其它工具為開發(fā)者節(jié)省寶貴的時間與資源，比方說可以通過APImatic.io等提供者為用戶提供自動生成多種語言的SDK的能力。使用APImatic.io無需手動編寫這些SDK，也不必依賴于社區(qū)保持它們的更新，它可以讓你簡單的導入RAML規(guī)范，隨后生成面向Java、Python、PHP、Ruby、AngularJS、iOS和 Windows等平臺和語言的SDK。

超越代碼

RAML正逐漸成為API規(guī)范方面的領頭人之一，與Swagger和API Blueprint并駕齊驅(qū)?，F(xiàn)如今已有越來越多的API方案提供者支持這一格式了（包括管理與工具等方面）。

為了加快發(fā)展的腳步，同時確保規(guī)范的完整性，在RAML于2013年問世的同時，一個由API領域驅(qū)動的工作小組也一并成立了。該工作小組將負責指正RAML的發(fā)展方向，確保它將繼續(xù)遵循最佳實踐，并符合業(yè)界的需求。目前，該工作小組由來自MuleSoft、AngularJS、Intuit、Airware、PayPal、API Science、Akana和Cisco的代表所組成。

RAML的出現(xiàn)不過一年多的時間，目前1.0版本的工作還在進行之中，新版本的目標是提供更多的功能，并且更好地滿足業(yè)界的需求，同時推進API的最佳實踐。當然，它也面臨著一些挑戰(zhàn)，包括如何定義與描述超媒體，這一點在所有的主要規(guī)范中都被提及。

如何為克服這些挑戰(zhàn)作出貢獻

開源社區(qū)的優(yōu)點就體現(xiàn)在這里，新的點子總是能夠找到立足之處。每個有志之士都可以通過訪問RAML.org加入這一項目，并且在GitHub上貢獻獨創(chuàng)的工具，或是創(chuàng)建規(guī)范的分支。畢竟，RAML的強大之處不僅僅在于目前它所實現(xiàn)的部分，即通過一個單一數(shù)據(jù)源，通過可視化的方式進行API的設計、創(chuàng)建原型、構建、共享以及進行文檔化，而在于它將如何對未來產(chǎn)生持續(xù)性的影響。

關于作者