第四章 系統設計與實作
4.2 伺服器端之系統設計
4.2.4 伺服器端 API
我們將伺服器端提供的功能包裝為一組 API，供客戶端程式、網頁瀏覽器以及第三 方系統存取。客戶端以 HTTP 呼叫這些 API，伺服器提供相應的服務，API 的回應以及 輸出資料則為 XML 格式，以方便呼叫端處理回傳的資料。文字編碼則考量國際化的需 求，為 UTF-8。
API 回傳的訊息有兩種，若失敗會回傳：
<result type="error"> //result type 為 error <errtype>SOME_ERROR_TYPE</errtype> //錯誤類型
<message>SOME_ERROR_MESSAGE</message> //錯誤訊息
</result>
成功則有兩種可能，若是要求進行某個動作（如要求登入），成功會回傳：
<result type="success"> // result type為 success <message>SOME_SUCCESS_MESSAGE</message> //某動作成功的訊息
</result>
若是向伺服器要求資料（如要求聯絡人清單），則是下列的格式
<result type="TYPE_OF_DATA"> //result type為資料的類型
<data1> //以 XML 表示的資料列表
</result>
各 API 以功能區別，描述如下：
使用者認證、登入階段管理 z api_login
參數：username, password
客戶端登入，傳入使用者之帳號密碼，系統會根據帳號密碼來確認使用者的身 份 ， 若 成 功 ， 會 啟 動 一 登 入 階 段 (session) ， 並回 傳 成 功 訊 息 。 必 須 先 以 api_login 登入，才可呼叫其餘的 API，否則系統會拒絕用戶端的 API 呼叫，並 回傳 AUTH_NOT_LOGIN_YET 錯誤。
可能回傳的失敗類型：
AUTH_LOGIN_ERROR：登入錯誤
z api_logout 參數：無
客戶端登出，呼叫時系統會結束之前呼叫 api_login 所建立之登入階段。若成 功會回傳成功訊息。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
z api_keep_alive 參數：無
維護目前進行中的登入階段，避免因為逾時而被系統判定客戶端已離線。不過 登入後呼叫任何 API 存取時，伺服器都會隱含地進行這個動作，故此 API 是供 客戶端已知自己一段時間不會與伺服器端溝通，而又必須維護登入狀態時使用。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
z api_get_activities 參數：無
回傳某使用者目前進行中的所有登入階段內容。
成功時回傳的資料格式如下：
<result type="activities">
<activity>
<sessionid>[ID OF SESSION1]</sessionid>
</activity>
<activity>
</activity>
...
</result>
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
使用者認證、登入階段管理 z api_get_profile
參數：無
供客戶端取得使用者的個人資訊，包含使用者名稱、電子郵件帳戶、偏好設定 等。密碼因為是以單向加密儲存在資料庫，故不回傳給客戶端，若客戶端要更 改密碼，可以使用 api_set_profile。
成功時回傳的資料格式如下：
<result type="profile">
<username>[USERNAME OF USER]</username>
<nickname>[NICKNAME OF USER]</nickname>
<email>[EAMIL OF USER]</email >
<preference>[PREFERENCE OF USER]</preference>
</result>
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
z api_set_profile
參數：nickname、password、email、preference
設定使用者個人資料，包括密碼，暱稱、電子郵件位址以及偏好設定。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
聯絡人與群組管理 z api_add_contact
參數：cid,given_name,surname,telephone_number,cellphone_number, fax_number,address_state_or_province,address_country,address_city,ad dress_street,email,msn,skype
根據傳入的資料在伺服器端資料庫裡新增一個聯絡人，如果有傳入 cid 欄位，
就會將新聯絡人的 Contact ID 設定為傳入的 cid，若沒有則由伺服器自動產 生。此動作會將新聯絡人之 LAST_MODIFICATION_TIME 設為產生此聯絡人時之 時間。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
CONTACT_EMPTY_INFO：傳入的聯絡人資料為空
z api_delete_contact 參數：cid
根據傳入的 cid，從伺服器端資料庫裡刪除指定 Contact ID 的聯絡人。同時 也會砍除 GROUP_ENTRIES 裡包含此聯絡人 CID 之記錄。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入 CONTACT_EMPTY_CID：傳入的 CID 為空
z api_modify_contact
參數：cid,given_name,surname,telephone_number,cellphone_number, fax_number,address_state_or_province,address_country,address_city,ad dress_street,email,msn,skype
根據傳入的資料修改伺服器端資料庫裡由 cid 指定的聯絡人資料。此動作會將 聯絡人之 LAST_MODIFICATION_TIME 設為修改聯絡人資料時之時間。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入 CONTACT_EMPTY_CID：傳入的 CID 為空
z api_get_contacts 參數：cids
參 數 cids 為 聯 絡 人 Contact ID 之 序 列 ， 各 CID 間 以 逗 號 分 隔 (cid1,cid2,cid3,...)。伺服器端會傳回 cids 指定之複數聯絡人資料，若未指 定 cids，則會回傳屬於該使用者之所有聯絡人資料。
成功時回傳的資料格式如下：
<result type="contact_list">
<contact>
<cid>[CID OF CONTACT]</cid>
<surname>[SURNAME OF CONTACT]</surname>
<given_name>[GIVEN NAME OF CONTACT]</given_name>
<telephone_number>[TELEPHONE # OF CONTACT]</telephone_number>
<cellphone_number>[CELLPHONE # OF CONTACT]</cellphone_number>
<fax_number>[FAX # OF CONTACT]</fax_number>
<address_state_or_province>
[ADDRESS - STATE OR PROVINCE OF CONTACT]
</address_state_or_province>
<address_country>
[ADDRESS - COUNTRT OF CONTACT]
</address_country>
<address_city>
[ADDRESS – CITY OF CONTACT]
</address_city>
<address_street>
[ADDRESS – STREET OF CONTACT]
</address_street>
<email>[E-MAIL OF CONTACT]</email>
<msn>[MSN MESSENGER SIGNIN NAME OF CONTACT]</msn>
<Skype>[SKYPE SIGNIN NAME OF CONTACT]</skype>
<last_modification_time>
[LAST MODIFICATION TIME OF CONTACT RECORD]
</last_modification_time>
<msn_status>[MSN MESSENGER STATUS OF CONTACT]</msn_status>
<skype_status>[SKYPE STATUS OF CONTACT]</skype_status>
</contact>
<contact> ... </contact>
...
</result>
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
z api_add_group 參數：gid,name
根據傳入的群組名稱在伺服器端資料庫裡新增一個群組，如果有傳入 gid 欄位，
就會將新群組的 Group ID 設定為傳入的 gid，若沒有則由伺服器自動產生。此 動作會將新群組之 LAST_MODIFICATION_TIME 設為產生此群組時之時間。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
GROUP_EMPTY_NAME：傳入的群組名稱為空
z api_delete_group 參數：gid
根據傳入的 gid，從伺服器端資料庫裡刪除指定 Croup ID 之群組。同時也會砍 除 GROUP_ENTRIES 裡關於此群組之記錄，包括此群組所包含之元素，以及包含 此群組為元素之群組。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入 CONTACT_EMPTY_GID：傳入的 GID 為空
z api_modify_group 參數：gid,name
根據傳入的資料修改伺服器端資料庫裡由 gid 指定之群組資料。此動作會將該 群組之 LAST_MODIFICATION_TIME 設為修改群組資料時之時間。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入 CONTACT_EMPTY_GID：傳入的 GID 為空 GROUP_EMPTY_NAME：欲修改之群組名稱為空
z api_get_groups 參數：gids
參 數 gids 為 群 組 Group ID 之 序 列 ， 各 GID 間 以 逗 號 分 隔 (gid1,gid2,gid3,...)。伺服器端會傳回 gids 指定之複數群組資料，若未指定 gids，則會回傳屬於該使用者之所有群組資料。
成功時回傳的資料格式如下：
<result type="group_list">
<group>
<gid>[GID OF GROUP]</gid>
<name>[NAME OF GROUP]</name>
<last_modification_time>
[LAST MODIFICATION TIME OF GROUP RECORD]
</last_modification_time>
<entries>
</result>
可能回傳的失敗類型：
z api_add_entry_to_group 參數：gid,id
將 id 指定之元素加入由 gid 指定之群組為群組元素，id 可為 cid 或 gid。此 API 會檢查母群組以及元素是否將形成循環包含，若形成循環包含則會拒絕要求並 回 傳 錯 誤 類 型 。 加 入 一 個 群 組 元 素 將 會 使 母 群 組 gid 之 LAST_MODIFICATION_TIME 改變為加入群組元素之時間，但不會改變群組元素 id 之 LAST_MODIFICATION_TIME。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入 GROUP_EMPTY_GID：傳入的 GID 為空 GROUP_EMPTY_ID：傳入之群組元素 ID 為空 GROUP_PARENT_UNEXISTED：指定之母群組不存在 GROUP_INVALID_ENTRY_ID：傳入之群組元素 ID 不正確 GROUP_ENTRY_UNEXISTED：指定之群組元素不存在 GROUP_CYCLIC_ENTRY：加入群組元素將形成循環包含
z api_delete_entry_from_group 參數：gid,id
將群組元素 id 自 gid 指定之群組中刪除，id 可為 cid 或 gid。刪除群組元素並 不會將該聯絡人或群組自資料庫中刪除。刪除一個群組元素將會使母群組 gid 之 LAST_MODIFICATION_TIME 改變為刪除群組元素之時間，但不會改變群組元素 id 之 LAST_MODIFICATION_TIME。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入 GROUP_EMPTY_GID：傳入的 GID 為空 GROUP_EMPTY_ID：傳入之群組元素 ID 為空
GROUP_PARENT_UNEXISTED：指定之群組元素不存在
z api_clear_all 參數：無
清空目前使用者所擁有之所有聯絡人與群組內容。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
聯絡人上線狀態更新
z api_set_presence.php 參數：type,cids,status
設定聯絡人之即時通訊上線狀態。type 指定上線狀態的類型, 如 msn, Skype,…
cids 指 定 要 設 定 狀 態 的 聯 絡 人 CID 序 列 ， CID 間 以 逗 號 分 隔 (cid1,cid2,...)status 指定對應 cid1,cid2,...的上線狀態，也以逗號分隔 (status1,status2,...)。接受的參數值視 type 類型而不同，msn 類型與 skype 類型可接受之狀態值根據 MSN 與 Skype 之官方設定訂定，列於錯誤! 找不到參 照來源。。若 cids 與 status 包含之序列長度不同，會以 cids 為主，若 cids 數量比 status 少，則剩下的會設為 MSN_UNKNOWN、SKYPE_UNKNOWN。若只有傳入 type 而 cids 為空，則會全部設成 status1，若沒有 status1, 則會設成 MSN_UNKNOWN、SKYPE_UNKNOWN。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
PRESENCE_UNKNOWN_TYPE：系統不認識指定之上線狀態類型
表6 聯絡人上線狀態可接受之參數 msn 類型之狀態 skype 類型之狀態
MSN_ONLINE SKYPE_ONLINE MSN_OFFLINE SKYPE_OFFLINE MSN_AWAY SKYPE_AWAY MSN_IDLE SKYPE_NA MSN_BE_RIGHT_BACK SKYPE_DND
MSN_BUSY SKYPE_SKYPEME MSN_ON_THE_PHONE SKYPE_SKYPEOUT
MSN_OUT_TO_LUNCH SKYPE_UNKNOWN*
MSN_UNKNOWN*
伺服器端時間存取
z api_get_server_time.php 參數：無
取得目前伺服器端之時間，可作為同步比對之用。傳回之時間時區皆為 GMT，格 式為 ISO 8601：YYYY-MM-DD HH:NN:SS。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
z api_get_last_modification_time.php 參數：無
取得目前伺服器端屬於目前使用者之群組與聯絡人最後修改時間，可做為客戶 端判定是否更新資料之依據。傳回之時間時區皆為 GMT，格式為 ISO 8601：
YYYY-MM-DD HH:NN:SS。
可能回傳的失敗類型：
AUTH_NOT_LOGIN_YET：尚未登入
除上述之 API 傳回錯誤類型外，若伺服器端在執行 API 之過程中出現錯誤，也可能 回傳一些錯誤類型：
DB_CONNECTION_ERROR：資料庫連線錯誤 DB_SELECTION_ERROR：資料庫選擇錯誤 DB_QUERY_ERROR：資料庫查詢錯誤