almost 8 years ago

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 等著接 API。如果對方等不及,你會採取 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。這裏我也分享幾個資源:

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

← [新書上市] Growth Hack 這樣做:打破銷售天花板,企業最搶手的成長駭客實戰特訓班 [分享][文件]工程團隊做事的基本原則 →
 
comments powered by Disqus