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_idclient_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
  • 除非有例外說明,PUTPOST 的上傳資料一律在 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
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.