Skip to content
This repository was archived by the owner on Jan 31, 2025. It is now read-only.

Home

Jump to bottom
Ingram Chen edited this page Nov 20, 2017 · 28 revisions

kaif Open API 開發指南

快速小抄

  • kaif OAuth2 授權步驟
  • OAuth2 授權網址 https://kaif.io/oauth/authorize
  • OAuth2 token 網址 https://kaif.io/oauth/access-token
  • OAuth2 所有的 scope=public user feed article debate vote
  • client_id 與 client_secret 可在 開發者應用程式 申請與查詢
  • API 的 base url 是 https://kaif.io/v1
  • 一個簡單測試用的 API 網址 (GET) https://kaif.io/v1/echo/current-time
  • Android 範例程式源碼

kaif API 串接流程

  • 從使用者的角度

    • 用戶打開你的 app
    • 點擊你 app 上的 登入鈕
    • app 開啟網頁到 kaif 授權網頁
    • 用戶確認權限無誤後，按下 kaif 網頁的授權鈕
    • kaif 網站彈回你的 app
    • 用戶可以開始使用 kaif API 提供的相關功能

  • 從開發者的角度

    • 開發者先去 開發者應用程式 申請一個 app，填好 callback_uri
    • 在 app 登入鈕按下時，導到 kaif 授權網址 https://kaif.io/oauth/authorize，並且包含必要參數
    • 用戶授權成功後，kaif 授權網站會回傳 授權狀 (authorization_code) 到你指定的 redirect_uri，你的 app 要能收網址的 redirect
    • app 收到授權狀後，在背後打一個 http POST 到 token 網址 https://kaif.io/oauth/access-token，並包含剛才的授權狀
    • POST token 網址成功的話，會回傳 access_token，這個 token 可以用來呼叫 kaif Open API (token 要存在你的 app 裡)

OAuth2 授權步驟

  • 上面的開發者角度就是 OAuth2 授權的流程，請務必參照 kaif OAuth2 授權步驟 的說明，一步步執行。

API 呼叫說明

  • API 文件
  • 每項功能都有限定的 OAuth2 scope，例如操作文章相關的功能就需要 article scope。
  • 注意即使查詢的內容是公開的 (例如 kaif 首頁的熱門文章列表)，也需要授權 scope。公開的內容通常被歸類在 public scope。

API 慣例

  • 透過 https://kaif.io/v1/... 存取，注意安全網址 https
  • 取得資料用 http GET，新增資料用 PUT，修改則是用 POST
  • Content-Type 一律是 application/json
  • 除非有例外說明，PUT 與 POST 的上傳資料一律在 body 放 json
  • 出現在網址的變數名，例如 path, parameter 單字都是用 - 隔開，而出現 json 欄位的，變數名都是 camelCase。

API 呼叫範例

  • 以下是取得自己的個人資料的範例 (GET)，注意 OAuth2 定義的 header Authorization: Bearer ... 一定要正確
curl -H 'Authorization: Bearer --YOUR-ACCESS-TOKEN--' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -XGET 'https://kaif.io/v1/user/basic'

# 回傳的結果:

{
  "data" : {
    "username" : "KaifLover",
    "description" : "kaif **很棒的**",
    "createTime" : "2015-02-15T07:21:43Z"
  }
}
  • 以下是 POST 的範例 (echo 你的輸入)
curl -H 'Authorization: Bearer --YOUR-ACCESS-TOKEN--' \
     -H 'Content-Type: application/json;charset=UTF-8' \
     -XPOST 'https://kaif.io/v1/echo/message' \
     -d '{"message":"Hello world!"}'

# 回傳的結果:

{
  "data": "Hello world!"
}

API 回應格式

  • API 回傳都會用物件包覆，放在 data 欄位裡，如下：
{
   "data": {
      "username": "DemoUser",
      "createTime": "2015-03-01T14:33:20Z"
   }
}
  • 如上例所示，時間欄位通常名稱結尾是 Time 或是 Date，以字串方式呈現，格式一律為 ISO8601，UTC 時區

API 錯誤格式

  • 呼叫 API 出錯時， 一般情況下 會用 errors array 包覆，如下：
{
   "errors": [
      {
         "status": 400,
         "title": "missing parameter"
      }
   ]
}
  • errors 裡一定是個 array，其內部物件的 title 是錯誤訊息，status 則是 http status code
  • 下錯參數一般都是回應 status:400，跟權限有關的錯誤是 status:401 或 403。server 本身有問題則是 status:500
  • 依照 OAuth2 的規範，呼叫 API 時與授權有關的錯誤，會列在 response header 的 WWW-Authenticate 裡
  • 注意 不是所有的錯誤都能夠好好的以 json errors 回傳，某些錯誤可能沒有內容，或是內容不是 json，錯誤訊息僅供除錯時參考。如果你要 parse 錯誤時的結果，請注意格式不會都是正確的。

API 使用注意事項

分享連結

用戶分享連結時，API 不會直接拒絕重覆連結。為避免重覆的文章分享，建議建立文章前，先檢查該連結是不是被分享過了，你可以使用 API：

GET /v1/article/zone/{zone}/external-link?url=foo

取得已經分享該連結的文章 (最多三則)，如果查詢結果是已經分享過了，建議引導用戶到那些舊文章。

另一個類似的 API 只檢查該連結有沒有分享過，如果你不需要文章可以用這個：

GET /v1/article/zone/{zone}/external-link/exist?url=foo

範例程式

kaif Open API 備有完整的 android 範例供實作參考，源碼在 Android 範例程式源碼

相關資訊

Clone this wiki locally