API

##基本的JSON回應格式 每個API method都應該要有

{
    "status": int (reference to the following table),
    "message": string (if status code cannot explain status in detail, here is more detail message),
    ...
    (other information returned by each api)
    ...
}

注意：若API為列出清單之類的請求，如果系統無資料的話，會回傳空的清單

• 這並非錯誤喔 >.^~

範例

{
    "status":0,
    "message":"Success",
    "data":[
        {
            "eid":"1",
            "time":"2015-03-10 19:00:00",
            "name":"\u8acb\u554f\u60a8\u4eca\u5929\u8981\u4f86\u9edePython\u55ce\uff1fDay 1"
        },
        {
            "eid":"2",
            "time":"2015-03-17 19:00:00",
            "name":"\u8acb\u554f\u60a8\u4eca\u5929\u8981\u4f86\u9edePython\u55ce\uff1fDay 2"
        },
        {
            "eid":"3",
            "time":"2015-03-24 19:00:00",
            "name":"\u8acb\u554f\u60a8\u4eca\u5929\u8981\u4f86\u9edePython\u55ce\uff1fDay 3"
        },
        {
            "eid":"4",
            "time":"2015-03-31 19:00:00",
            "name":"\u8acb\u554f\u60a8\u4eca\u5929\u8981\u4f86\u9edePython\u55ce\uff1fDay 4"
        }
    ]
}

參數

呼叫API時，可以用以下方式傳遞參數

• HTTP GET的key-value
• HTTP POST的key-value
• HTTP POST的json

（也可以混用，如以get傳遞token，再以post傳遞其他參數包成的json）

token為所有API皆需要之參數

如呼叫/api/get-nid，可傳送以下json至API

{
    "token": "put_token_here",
    "cid": "put_cid_here"
}

注意參數名稱大小寫：

• ID類型為全小寫，如nid、cid、eid
• 其餘採小寫開頭駝峰命名法，如eventParticipantList

名詞解釋

1. nid -> NID(恩)
2. cid -> 卡片ID
3. eid -> 活動ID
4. vid -> 投票ID

Status Code (In Json)

Code	Description
0	Success
1	Permission Denied (Wrong Token?)
2	Arguments Error (Too many, less or Not Equal)
3	Check In/Out Failed (Not Member or No NID)
4	Bind Failed (Same NID/CID or Not Member)
5	Data Not Found (Not Member or no event)
6	Not Match (nid and cid not belong to same card)
-1	No Respone (Server is busy?)

卡片資料

做好了	URL	Argv	Return(Success/Failed)	Description
✔	/api/list-cards	[timeOnly=false]	[(nid, cid)],timestamp/(Failed)	列出卡片(若timeOnly為true，則只顯示最新版本時間戳)
✔	/api/bind-nid	nid, cid	(Success)/(Failed)	NID及卡號配對
✔	/api/get-nid	cid	(nid)/(Failed)	取得對應的NID
✔	/api/get-cid	nid	(cid)/(Failed)	取得對應的CID
✔	/api/get-card-data	nid or cid	(card data)/(Failed)	取得卡片資料(同網頁端的卡片清單頁面)

活動管理 (包含社課)

做好了	URL	Argv	Return(Success/Failed)	Description
✔	/api/list-events		[(eid, time, name)]/(Failed)	列出活動
✔	/api/get-event-data	eid	(time, name, category)/(Failed)	取得活動資料
✔	/api/get-event-participant	eid	(time, name, participants)/(Failed)	取得活動參與者列表

活動簽到

做好了	URL	Argv	Return	Description
✔	/api/check-in	eventParticipantList	(Success)/(Failed)	簽到
###eventParticipantList格式
####說明

• eid：活動編號
• attendee：參與者（物件陣列，每項包含nid、time。此項目細節出錯直接略過，不噴錯）
  • nid：簽到者NID（無卡片資料或重複簽到者，直接自動跳過）
  • time：簽到時間（Unix Timestamp，缺少、格式錯誤或無效者，自動填上當前時間）

####範例

{
  "eid": "5566",
  "attendee": [
    {
      "nid": "D0000000",
      "time": 123123123
    },
    {
      "nid": "D0000001",
      "time": 123123321
    },
    {
      "nid": "D0000002",
      "time": 123123111
    }
  ]
}

登入取得API token

做好了	URL	Argv	Return	Description
✔	/api/get-token	username, password	(token)/(Failed)	取得token

投票系統

Done	URL	Argv	Return	Description
	/api/add-vote-list	vote-user	(Success)/(Failed)	將卡號對應的用戶加入投票佇列

###vote-user格式 ####說明

• vid：投票編號
• nid：簽到者NID（無卡片資料或重複簽到者，直接自動跳過）

####範例

{
  "vid": "5566",
  "nid": "D0000000"
}

---

已廢棄 (總之下面這邊先當作沒看到)

URL	Perm	Argv	Return	Description
/User/addUser	Admin	NID	json(Success)	新增用戶
/User/editUser	Admin	NID	json(Success)	更新用戶
/User/delUser	Admin	NID	json(Success)	刪除用戶
/User/getUserData	Admin	NID	json(UserData)	取得用戶資料
/Event/addEvent	Admin	EID	json(Success)	新增活動
/Event/editEvent	Admin	EID	json(Success)	更新活動
/Event/delEvent	Admin	EID	json(Success)	刪除活動
/API/check-out	Admin	CID	json(Success)	簽退(預留)