Intro to RAML - API Spec Driven Development

over 8 years ago

Intro to RAML - API Spec Driven Development

API Engineer 這個職缺，隨著 Mobile Application 爆炸性的成長，與架構 Micro Service 化，逐漸炙手可熱。但是，卻沒有工程師把握自信的說，自己很會「設計」 API。

API 變得越來越重要。但是工程師們卻都視「設計」API 為燙手山芋。大家有心想設計出好的 API，容易讓下游使用。想寫好的文件，讓後人容易維護。但是這個「想」，卻從來是有心無力的議題。

今天在這篇文章，我想同時介紹兩個東西

RAML - RESTful Modeling Language
Spec Driven Development

解放大家的痛苦。

API 是大家心中永遠的痛

為什麼很多人畏懼碰觸這個議題。這是因為：

因為「建」（build）API 很簡單。
「設計 API」很困難。
「維護API」很困難。
「寫文件」很困難。

傳統來說，一般 RD 的開發 cycle 是這樣的：

第一種狀況：寫 API （射後不理）=> 改 API （崩潰）
第二種狀況：寫 API => 補 TEST => 寫文件 => 擴增 API => 補 TEST => 改文件（精神崩潰）
第三種狀況：TEST DRIVERN （寫 TEST ) => 寫 API => 補文件 => 修改 TEST CASE => 擴增 API => 改文件（精神崩潰）

API 開發讓 RD 感到壓力主要的問題，是因為不管採取 BUILD FIRST 或者是 TEST FIRST 的策略。「維護成本都很高」，而一旦開發完畢，後面接著應更動文件，甚至變成了「壓死駱駝的最後一根稻草」。

而這當中最大的原因。主要是因為寫 API，後面一定至少有一個以上的 RD 等著接ＡＰＩ。如果對方等不及，你會採取 build first，直接 API 直接給他接。如果對方可以接受晚一點接，你會先 test driven，先 build test case，確定 API 不會爆炸，晚一點補文件給他。

文件很重要，但是大家都不喜歡寫文件

我們都知道文件很重要。但是幾乎工程師都不喜歡寫文件。系統的 code 瞬息萬變，誰有精力去寫文件呢？code 改完，還要補文件修改，老闆又不會多發一點薪水給我？

但最主要的問題是

不想要維護兩套文件（程式碼註釋、API 本身文件）
文件沒有立即性的用處。

這年頭有人甚至提倡 Spec Driven Development。但往往大家聽到這個名詞，通常卻覺得只是開玩笑而已。因為

只有大公司節奏慢，經得起這樣耗，可以先寫文件再補 Test，反正公司有的是美國時間。小公司立刻就要有產出，誰跟你 Spec Driven 或 Test Driven。
先寫文件，不先寫 API，下游 RD 絕對砍死你。
先寫文件，產出的成果不會加速開發。不如先寫程式，由程式自動產生文件。所以即便 Swagger 有 API designer，但是大家還是偏好由 Swagger 掃描程式產出文件，而不是先用 Swagger 設計 API。

這就帶出了下面我想要介紹的這一套的解決方案：RAML。

RAML - RESTful API Modeling Language

RAML 全名為 RESTful API Modeling Language。是一套基於 YAML 格式的新 API 標準規範。這套規範同時符合兩個特性：

機器可讀
人類可讀

你可以直接用 RAML 設計 API 文件，詳細定義裡面的 meta，response，error, test case。
然後用工具產生 API 文件。這是 RAML 的一個範例：

%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 designer：mock backend

當然，產生 API 文件很多家工具都做得到。這沒什麼了不起的。但是 RAML 生態圈的這群人並不僅止於滿足產生文件。他們想的甚至是用 API 產生 mock backend service。

也就是當你用 RAML 設計完文件，連「假後台都寫好了」。也就是當文件寫好，你不必真的寫程式，你可以用工具將 RAML 轉成實際的 backend，讓你的下游 RD 直接對接，讓他實際使用，看看 API 設計得合不合理。

如果不合理，「修改文件」就可以了。你不必改 code。甚至到這時候你連一行 code 都不用寫。

為什麼 RD 對 API 的開發、修改視為畏途。是因為

要實際開發程式碼
要寫測試
要寫文件

這造成了只要下游要求修改一個小小的結構，或擴充一組小小的功能，就會耗上一整天的時間。所以有時候即便 API 設計有瑕庛，原設計者也不是很願意修改。而且 API 開發的週期釋出太長，所以版本號甚至難以管理，或根本「不管理」（一直以來都保持在 0.1）

使用這個 RAML 以及 Spec Driven Development，你可以先用 RAML 改到下游高興為止，都還不必寫一行真正的 code。

就算要寫測試，也只要先對這組假 API backend 寫就好了。

RAML API proxy

甚至是這些工具，都還可以內建 API proxy 的功能。（這一點也蠻重要的）

因為 API 上線之後。可能也要面臨的一些挑戰是：

authentication / authorization
throttle
scalability / stability

特別是 Mobile 方面的 API ，用量都蠻大的。自幹 API 大概有點緩不濟急。前面擋個 API proxy，真的事情會變比較容易。

Summary ：終結惡性循環

多數 API 的低維護性，多半出自於開發循環中的「技術負擔」（開發 + 測試 + 文件）徹底壓垮 RD 想要「整理」「根據回饋修改端口」的意願。

RAML 的出現算是把這個惡性循環終結了一大部分。如果你想對 RAML / Spec Driven Development / Design Perfect API。這裏我也分享幾個資源：

http://raml.org/ （官網，寫得很好）
http://apiworkbench.com/ （RAML 1.0 同時釋出的 Atom 外掛）
http://www.slideshare.net/mulesoft/building-your-api-for-longevity ( Mike Stowe 的投影片）
http://www.amazon.com/gp/product/1329115945/ Undisturbed REST: a Guide to Designing the Perfect API

希望各位能夠少爆一點肝。

May 12, 2016 02:29
Permalink
Comments