API Hub

呼叫之前,先知道要準備什麼。

每個版本怎麼認證、規格文件放在哪裡、量到了什麼,都寫在版本底下,並標明是誰說的、什麼時候說的。

三張淺藍色厚紙交疊,角落各有一圈空白的方形壓紋,底下露出深灰藍紙面。

寫在版本上

認證方式與規格文件,記在每一個版本上。

同一個 API 的兩個版本,認證方式可能不一樣。所以這些事實跟著版本走,每一筆都標明出處。

  • 認證方式

    免認證、API 金鑰或使用者授權,記在每一個版本上。新版本改了認證方式,舊版本的紀錄不會跟著改。

  • 規格文件

    條目記下規格文件在哪裡、由誰提供、哪一天確認的。

  • 量測

    量測結果一定附上指標、方法、條件、單位與時間。

  • 出處

    每筆事實都標明出自提供者、從公開資料匯入,還是社群量到的。匯入的資料附上來源與授權的連結。

量測和評分是兩回事。評分是大家的看法;量測說的是,在什麼條件下量到了什麼。

量測

一筆量測,先讀這五項資訊。

先讀指標、方法、條件、單位與時間;比較時,也要核對結果、對象與涵蓋範圍。

  • 指標

    量的是什麼。

  • 方法

    用什麼方法量。

  • 條件

    在什麼情況下量。

  • 單位

    數值用的單位。

  • 時間

    哪一天量的。舊的結果,標著舊的日期。

同一個指標的結果累積成歷史,也能和其他 API 放進同一張比較表。

缺少的資料

未知、零、不適用,是三種答案。

沒量過就是未知,不會被寫成零;不適用的指標,也不會被當成缺資料。缺少的資料,不會變成誤導人的分數。

先知道怎麼認證,再開始串接。

用一個帳號找 API、追蹤改版,也把串接的經驗留給下一個人。