API討論

[jyhsu2000]

1. 如何檢查客戶端（請求端）的合法性？還是直接Open？
2. 希望有哪些API？（發送參數、成功回傳、失敗回傳...等資訊）

預計網址：http://hackersir.info/api/動作 請求類型：POST/GET 型態：JSON 共同必要參數：token 共同回傳：success: true/false

目前想到的API... （空白都是還沒想法的）

動作名稱	功能	參數	成功回傳	失敗回傳
	記錄NID與卡號對應	nid card_number
	取得NID	card_number	nid
	簽到	nid time

[vongola12324]

如果直接Open，我會在一個學期內收到法院傳票....... 先問，檢查合法性的定義是？是否有權限存取社員資料嗎？

[jyhsu2000]

@vongola12324 是指權限沒錯 可能要實作類似api key之類的機制？

[vongola12324]

@jyhsu2000 一般不是手機端Login? 還是要實作Oauth2?

[jyhsu2000]

別一開始就挑戰那麼複雜的啦 OAuth2我也只會使用 實作就...A_A 何況手機端的數量應該只會是個位數

目前最簡單的方式 直接寫死幾組api key在程式內 （hash之後直接存在設定檔，或是再開個表來管理這個） 而手機端每次請求時 參數當中都必須有這個key 檢查正確API才會理你 或是每次使用時 必須先透過API key的驗證一次 在一段時間內該裝置都能存取

只是目前的想法啦 或許還有其他更好的方式

[timchengx]

先求有 再求好 以後再來慢慢改

以我這邊的角度來說 先定義好幾組寫死的 token 來呼叫感覺比較務實 建議每次api call都要附上token 然後看以後需求變複雜再看要怎麼改

另外Server端要注意以後的可擴充或是可修改性 不然以後改起來會抓狂 (；´Д｀)

[jyhsu2000]

@gnehcmit OK 那一開始就先寫死幾組token，每次呼叫都檢查 可擴充性不必擔心 其餘重點就在第2題了...

[vongola12324]

@gnehcmit @jyhsu2000 我原本的構想是用直接login（第一次），之後就根據系統發的token（第一次登入後發的）來登入。

還是我們現在直接把開發人員的帳號各綁一個token上去？

[timchengx]

也可以 @vongola12324 是在討論權限管理吧 你說的是指如何拿token 這可以再開個API出來 不影響其他API的功能

至於第二點 有請社長大大說說需要哪些功能？

[jyhsu2000]

手機端只是簽到系統 本身會動到的資料也不多 也不會碰到什麼會員資料 頂多就查看或建立NID跟卡號對應，還有新增簽到記錄 所以想說直接從API那邊用token限制

拿token方法 如果我們寫死的話 有以下方法：

1. 私訊跟我們要
2. 直接到原始碼內看Hash過的token，然後自己還原使用A_A

還是... 使用API前 必須登入任何一組幹部帳號？ 這種寫法也可以 只是...看網站的可用協定.... 這方法似乎不太安全呀...（苦笑

[jyhsu2000]

補充了一些 更新到最上面了 再來靠各位完善它了（？

[timchengx]

@jyhsu2000 我指的寫死是說目前為了要 快點上線 可以先暫定幾個token來用 建立暫時的allow token list... 之類的

後面可以再補上會員與token之間關係的管理功能(幹部可用此api, 管理者可用此api ...etc)

功能完善之後 再把急就章寫出來的東西拿掉

[timchengx]

@jyhsu2000 使用api前要登入任何一組幹部帳號會把問題弄得很～複雜 OTL 還是就簡單的token認證就好了吧

所以說token不能外流 外流的話要馬上關掉 然後可以設計使用紀錄...etc (這都是題外話　重點是先把核心api生出來阿阿阿阿阿)

[jyhsu2000]

我知道呀XD 由於是暫時的 所以想說加密放設定檔就好

當然你想要的權限區分之後也做的到 但不會是這幾天就是了... 到時候再看是想token綁帳號，再根據會員群組去分權限 還是直接token去分權限吧，不過之後再討論就好 那時也自然會把暫時應急的東西改掉

[timchengx]

ok 等 社長大大 @vongola12324 告訴我們需要哪些API =3=

[jyhsu2000]

@gnehcmit 那就麻煩大大先抽空幫我們把三個應該會加的api取個英文名稱吧（指最上面 或是看看那幾組有哪裡要改的

[vongola12324]

@gnehcmit 我可以拿Plurk API來當範例看需要哪些API嗎？

因為我現在也只想得到爬資料跟丟資料這樣

[timchengx]

@vongola12324 既然現在只想到需要這些 就先實作這些吧 有想到甚麼東西 以後可以再補帳 不過 @jyhsu2000 請記得可擴充性阿 QAQ (我也得筆記一下

[vongola12324]

一般來講失敗要回傳NULL、錯誤代碼還是例外啊？

下面暫定是錯誤代碼/w HTTP （200 = OK, 400 = Error)

動作名稱	功能	參數	成功回傳	失敗回傳
updateCID	記錄NID與卡號對應	nid, card_number	200	400
getNID	取得NID	card_number	nid	400
eventCheckIn	簽到	nid, time	200	400
getEventsList	取得活動列表	N/A	json(eventList)	NULL
getEventMember	取得活動出席人員	EventID	json(eventMemberList)	NULL

[timchengx]

動作名稱	功能	註解
set_card	記錄NID與卡號對應	((輸入是json array?
get_stuid	取得NID	((call 一次回傳一次? 學校網路GG的話 手機在那邊loading不就很冏?
event_checkin	簽到	((輸入是json array?

[timchengx]

阿呀 樓樓上已經有提了 名稱我是覺得都行啦 你們協調好我就配合吧 (棄權意味w

[vongola12324]

@gnehcmit 我晚點再補

[jyhsu2000]

由於框架和寫法架構限制 動作命名請全小寫，以「-」分隔 例如eventCheckIn應該要event-check-in

至於回傳... 如果不是統一JSON 而是有時JSON有時數字（200、400）或純文字（nid、NULL） 這樣寫手機端的各位會不會崩潰呀？A_A"

[timchengx]

嗯...一律要回傳正確的HTTP status call 與JSON字串 就算只是簡單確認訊息也這樣做

這樣統一應該比較不會亂 0.0

[jyhsu2000]

這就是麻煩的地方... Laravel的Response::json()一定是回200 至於能不能用其他方式回400... 我晚點試試看

[timchengx]

收到 如果HTTTP status code還沒辦法解決 就先擱置 另外開個issue吧 重點先產出JSON API XD

[vongola12324]

在json中包上status code如何？

[timchengx]

這樣很亂 一件事歸一件事吧 不然很ambiguous 0.0

[vongola12324]

會嗎？就直接根據json裏的status判斷狀況就好了？ HTTP Status Code就當作是有沒有收到回傳的通知就好了啊ＯＡＯ？

[timchengx]

你說的status code應該是指自定義的status包在 JSON嗎？ 這樣也行 我說會ambiguous是指JSON裡面還包http status code 0.0

[vongola12324]

@gnehcmit You got it. 大概就是那種感覺

[jyhsu2000]

測試結果 可以json+http ststus code 測試API： http://hackersir.info/api/test/200 http://hackersir.info/api/test/400 http://hackersir.info/api/test/418 ...如此之類的 後面可以自行換成任何有效的http status code

[timchengx]

HTTP 418 wwww 那接下來的更細部的json input & output呢?

[jyhsu2000]

1. 那成功或失敗就以http status code處理 而不包含在回傳裡面？

2.input 會希望是json？ 還是一般GET/POST常用的多組key-value？

3.output 格式為JSON 不帶成功或失敗的訊息 其餘看你們需要什麼？

[timchengx]

1. 好喔
2. 我覺得設計成可以吃json array會不會比較好? 只要POST一次就可以上傳多筆資料(例如上傳簽到時)
3. 好喔

@vongola12324 你有想要在android上面可以顯示卡片以及學號(或姓名)的對應嗎? 有的話取得nid與卡號的對應的API回傳要json array? (有鑒於學校網路很爛 所以要預先下載到手機)

[jyhsu2000]

突然想到...

POST參數傳遞方式： 將多組key-value包裝起來整個丟過去 解開一樣是多組key-value

GET參數傳遞方式： 將多組key-value放在網址 接收時透過?、&、=區分多組key-value

一般限制下 key：基於變數命名原則 value：字串或數字

那... 你打算怎麼丟JSON呀？

[jyhsu2000]

是說Laravel對POST預設有CSRF防護 雖然確實可以改代碼解除他 但不太建議 所以還是希望API是透過GET存取 （畢竟無法在沒產生表單的情況讓手機取得有效csrf_token...）

[vongola12324]

@gnehcmit 手機上我希望簡單化啦，顯示是否刷卡成功及錯誤訊息就好了（可能非社員、讀取失敗之類的）。

這樣應該比較簡單吧？如果在顯示說是誰會不會很麻煩？

[jyhsu2000]

API接觸到的部分還是限制住吧 我覺得主要功能就...

• NID綁卡號
• 透過NID取得卡號
• 透過卡號取得NID
• 簽到（給NID/卡號和時間，由網站系統自己去對應活動）

至於透過API取得不見得每個NID都會有的會員身份或是名字 還是歸到Features in future吧A_A

而活動清單我則是覺得沒那麼需要 畢竟是社課，因此不可能一天超過一場 同一天內的簽到都視為該天唯一活動的就好吧 即使有多場，也可以直接對應到「已經開始的最後一場」

一開始還是以簡單為主吧 要擴之後還有得擴

[timchengx]

@vongola12324 需要顯示 社員 非社員的話 手機就需要預載卡片資料

[timchengx]

@jyhsu2000 沒錯 :p

[vongola12324]

@jyhsu2000 簡單至上（咦？A_A

@gnehcmit 那就只顯示訊息就好，不顯示社員資料。ＯＫ？

[jyhsu2000]

@gnehcmit 有空請看一下這則

[timchengx]

@jyhsu2000 HTTP POST, GET時 使用

Content-Type: application/json

這樣可行嗎?

[jyhsu2000]

@gnehcmit GET無法 參數一定是key-value的形式 而且是直接接在網址後面 POST可以直接這樣做沒錯 我這邊也可以接收 但如果是POST傳遞的話 那就回到這則了 有必要的話，我是可以強行解掉這邊的CSRF防護啦

[timchengx]

@jyhsu2000 恩...

GET的應用大多帶token就好? 所以沒什麼影響?

[jyhsu2000]

@gnehcmit 那之後網址可能就是http://hackersir.info/api/動作/token囉～

API的CSRF保護弄掉了

剛剛新增一個測試API 單純把輸入的JSON重新印出 試試你那邊能否順利傳遞你要的資訊過去吧 餵JSON給他就行了

網址：http://hackersir.info/api/test-json 後面可接token：http://hackersir.info/api/test-json/put-token-here 請求類型：POST（其他方式會出現404） Content-Type: application/json

[timchengx]

稍微玩過了一下 問問 要不要把json的key名稱都全小寫啊 像是這家的api 一樣@@? http://pixabay.com/api/docs/

還有 return 不太需要回傳token吧? 弄成status就好?(通過驗證, 沒通過驗證?)

另外 API的404可以就單純傳個簡單的json就好嗎 如果手機端不小心弄成404 吃太多東西(咦XD 可能會炸掉

[jyhsu2000]

動作名稱採「全小寫的間隔命名法」（以「-」分隔） key的名稱看你們要用哪種 一般用「小寫開頭駝峰命名法」或是「全小寫的底線間隔命名法」比較多 我這邊是都能處理

[timchengx]

key的規則我沒意見 你們決定吧

我比較喜歡小寫開頭駝峰命名法 XD

[jyhsu2000]

404只會發生在API請求型態錯誤（例如規定用POST卻用GET） 或是根本網址打錯

至於其他如token錯誤、卡片不存在、學號已有卡片等等的錯誤 就看你們如何定義API錯誤時的回傳了