上屏API-概述
1.1.用途及閱讀方法
上屏API是上屏系統的後臺接口，管理平臺界面實現需要遵循本接口規範。
1.2.通信協議
客戶端和服務器通過HTTP協議通信，客戶端使用HTTP GET方法或POST方法向服務器發送請求，服務器返回json格式的業務數據或操作結果給客戶端。
盡管接口同時支持GET和POST方法，建議查詢數據時使用GET方法，修改和添加數據時使用POST方法。
1.4.接口請求
接口的請求地址是個URL地址，每個接口URL地址都包括接口位置和請求參數，例如：
http://ip/res/?action=get&token=123456 其中：
http://ip/res/ 是接口請求的URL位置，“ip”在實際請求中要替換成服務器的ip地址或域名。
其中：
action參數是在所有接口中都要有的，該參數表明了請求業務的類型。
token參數提供一個安全認證符號給服務器，服務器用token來驗證客戶端的合法性，除了登錄驗證接口之外，其他接口都需要token參數。
所有參數都可以采用GET或POST方法提交。在使用ajax提交時，應當在接口位置結尾加上反斜杠"/"，以免參數提交失敗。如：http://ip/res/
有關URL地址的編碼規範，請參考HTTP 1.1規範。
1.5.接口響應
服務器在收到接口請求後，首先判斷token的正確性，如果token錯誤，則返回認證錯誤的消息給客戶端。如果token
1.6.接口安全
客戶端必須首先通過身份認證才能繼續調用接口，在一個“挑戰—>應答”模式的身份認證過程中完成身份認證，認證通過後，服務器為客戶端分配一個臨時令牌token，在後續的請求中，token作為一項必選參數提供，服務器通過token識別用戶身份和驗證請求的合法性。
在沒有接口調用時，token的有效期為30分鐘，之後客戶端再調用接口時必須重新進行身份認證，獲取新的token。
為了確保一定的安全性，客戶端應妥善保存token值。
1.7.URL編碼
當URL請求參數值中包含URL地址保留字符時，應對參數值進行URL編碼。
當請求參數包含中文字符時，應對中文字符采用UTF-8編碼。
1.8.描述約定
本文檔在描述接口的URL地址時，如果沒有特殊說明，會省略掉URL前面的相同部分。
例如，
http://ip/res/?action=get&token=123456 簡化為 res/?action=get&token=123456
在描述參數時，省略token參數的描述，在示例中也會省略。在實際調用中必須把token參數加上。
在對參數進行描述時，用【必選】表示該參數必須提供，【保留】表示該參數可以接受但尚未被使用。
1.9.返回消息結構
返回的json消息數據結構具有嚴格的一致性，客戶端可以采用一致的接收和解析方式處理返回消息。
簡單消息
簡單的返回消息包含對請求的處理結果，結構如下：
{
"code":0,
"err_desc":""
}其中：
code 為 0 表示處理成功，其它值表示處理失敗。
err_desc是對錯誤的描述，在code為0時err_desc會被省略。
特殊情況，在用戶認證的login1和login2接口中，err_desc具有特殊用途用法，具體參見接口描述。除這兩個接口之外，err_desc都表示錯誤描述。
帶業務數據的消息
有的返回消息除了包含處理結果信息，還包含業務數據記錄集，結構如下：
{
"code":0,
"data":{
"count":1,
"items":[{
"server":"g3",
"ip":"127.0.0.1",
}]
}
}其中：
data 業務數據的根節點：
count 業務數據的條數，可能的值為0 ~ n
items 業務數據，是一個數組，數據條數由count屬性定義。當count為0時，items屬性可能為null或者不存在。
本文檔後續章節中，在描述items元素的屬性時，會省略一些屬性的描述，即實際調用接口返回的屬性在本文檔中可能會沒有描述，這種情況下請直接忽略被忽略描述的屬性值。本文檔中描述的屬性是實際返回內容的一個子集，沒有描述到的內容對集成本系統沒有影響。
帶分頁數據的消息
如果返回數據較多，服務器會對返回的數據進行分頁，客戶端可以按照頁碼請求指定範圍的數據。帶分頁信息的返回數據結構如下：
{
"code":0,
"data":{
"page":1,
"page_size":"20",
"pages":"1",
"total":"2",
"count":2,
"items":[...]
}
}分頁數據信息在data元素下，意義如下：
page 當前頁碼
page_size 每頁數據記錄條數
pages 總共的頁數
total 總數據條數
count 當前返回頁的數據條數
如果返回的數據帶有分頁信息，則可以在調用接口時使用page參數來請求指定頁碼的數據。
1.10.參考
[1] RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1[S].
[2] RFC 3986, Uniform Resource Identifier (URI): Generic Syntax[S].
[3] http://www.json.org/ Introducing JSON
上屏API-概述