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

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

REST風(fēng)格的發(fā)明者Roy Fielding表示：“很不幸，人們很善于處理短期的設(shè)計(jì)，但對(duì)于長(zhǎng)期的設(shè)計(jì)通常就束手無(wú)策了?！?/p>

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

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

提示

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

API契約的設(shè)計(jì)周期

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

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

提示

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

API Console與API Notebook

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

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

舉例來(lái)說(shuō)，在下面這張截圖中，用戶能夠連接到Instagram的API，通過(guò)OAuth進(jìn)行驗(yàn)證，并嘗試搜索帶有“kitten”這個(gè)標(biāo)簽的圖片，一步一步完成設(shè)計(jì)過(guò)程。

(點(diǎn)擊放大圖像)

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

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

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

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

(點(diǎn)擊放大圖像)

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

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

人類可讀

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

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

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

在以上代碼中，我們首先聲明這是一個(gè)RAML規(guī)范，它對(duì)應(yīng)RAML 0.8（版本1很快就會(huì)發(fā)布了），并聲明API的標(biāo)題、基本URI、以及這個(gè)API的版本號(hào)（這個(gè)示例中的API是版本1）。

在RAML中聲明資源非常簡(jiǎn)單，只需使用/resourceName格式。而添加方法也同樣便捷，只需引用相應(yīng)的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讓你能夠定義多種相應(yīng)，返回不同的狀態(tài)碼、頭信息以及響應(yīng)體。例如：

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

舉例來(lái)說(shuō)，你可以在規(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

對(duì)開(kāi)發(fā)者十分友好

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

通過(guò)traits定義通用屬性

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

在創(chuàng)建trait時(shí)，你實(shí)際上是創(chuàng)建了一份模板，它能夠通過(guò)接受參數(shù)為方法提供屬性，只需幾行代碼就能夠完成。同時(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\"]"}]

通過(guò)ResourceTypes為資源定義模板

此外，與traits相似，resourceTypes也允許你為資源本身創(chuàng)建模板，以此調(diào)用通用的方法與響應(yīng)。打個(gè)比方，對(duì)于Collection這種資源類型來(lái)說(shuō)，你可能會(huì)大量用到POST與GET方法，并且通常會(huì)返回200、201或400等狀態(tài)碼。只要將它定義為一種resourceType，你就能夠通過(guò)兩行代碼就完成調(diào)用，而無(wú)需為你所創(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中定義可選的方法，只需為該方法加上一個(gè)問(wèn)號(hào)（？）即可。這種可選方法只有在定義了該方法的資源中才會(huì)被引入，這就為你賦予了更大的靈活性。

提示

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

自動(dòng)生成SDK

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

超越代碼

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

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

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

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

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

關(guān)于作者