前 引 范 基于RESTAPI的跨界服務接口設計規 附錄A智慧社區跨界服務案 附錄B智慧社區跨界服務API設計案 引本文件規定了智慧社區跨界服務的需求建模與基于RESTAPI的跨界服務接口設計。CrossoverMeta活動角色目標功能性目標FunctionalNon-functional約束分解資源表現層Presentation請求響應Status 統一建模語言（Unifiedmodeling 應用程序接口（ApplicationProgrammingInterface） 表現層狀態轉移（RepresentationalStateTransfer） 超文本傳輸協議（HyperTextTransferProtocol） 統一資源標志符（UniformResourceIdentifier） 開放接口說明文檔（OpenAPISpecification）擁有產生使用實現11名稱組織名稱類型名稱執行者名稱類型價值接口提供者消費者名稱1..*扮 1..*擁 產 22概況上下文環境名稱組織名稱類型名稱執行者名稱類型價值接口提供者消費者領域名稱上層目標和下層目標之間存在兩種分解關系：“與”和“或”。“與”關系意味著如果上層目標被選Q/BFW248-

0..*擁有

3概況上下文環境名稱組織名稱類型類型類型是否可操作目標操作操作對象實現方式類型達 名 組合類 44名稱類型名稱執行者名稱組合類型名稱領域質量提供者名稱名稱名稱基于RESTAPI在跨界服務流程模型分析的基礎上進行跨界服務開發與實現時，推薦基于RESTAPI進行服務接口設計。基于RESTAPI的跨界服務接口設計過程中，從API資源設計、API交互設計、API性能和非功能API資源（Resource）是一種網絡實體，是RESTAPI（Rpeenaona）URUnomReoucedene）ETUI只代表資源實體（位置），不代表其表現形式。使用不同的TP方法與R組合來實現對資源的不同ET資源命名（URI設計）是在創建易于理解和易于調用的WebAPI時最重要的概念。選擇資源的出發資源具有層次結構以及內部聯系。例如，在銀行領域中可以使用“/customers/{customerId}/accounts”來標識特定“客戶”的子集合資源“帳戶”。本節從層級嵌套和資源建模粒度兩方面來規范RESTAPIa

nespapersed/

比如URI：/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}，在上述例子中，dyno屬于app，app屬于org可設計RESTAPI時，選擇正確的資源并以正確的粒度對資源進行建模非常重要，關系到使用者是否表 RESTAPI屬性類型中以JSONID都能訪問，例如:/apps/{appid-or-name}。URI結構Web服務中，用于限制兩個或多個輸入參數的依賴關系從而獲取對服務的有API說明文件中，方便用6是常見屬性依賴模式。表 p1->p1p2p12Or(p1;p2;...;APIp1,...,pnOnlyOne(p1;p2;...;APIp1,...,pnAllOrNone(p1;p2;...;APIp1,...,pnAPI調用中，聲明屬性p1,...,pnRESTAPI支持服務器返回多種不同類型的資源，支持MIMEType，其網絡資源的具體表現形式，RESTAPIAcceptRESTAPI通過HTTP協議實現客戶端與服務器的通信，因此RESTAPI的設計規范需依賴對HTTP協議的規范使用。下面從請求和響應兩方面定義RESTAPI交互設計規范。RESTAPI要求使用HTTP協議定義的標準方法來對資源進行操作，具體描述見表7。對資源的常見表 類似于GET體中。POST請求可能會導致新的資源的建立和/HTTP/1.1是對PUT在某些情況下，客戶端庫或工具可能不支持HTTP協議PUTDELETE方法，此時建議的兼容方POSTPUT和DELETEAPIURL的查詢字符串中添加_method一項，指明POST替代的是PUT還是DELETE。RESTAPI的響應要符合HTTP1.1響應標準結構。針對資源的各種操作（HTTP請求方法）的不同9為常用HTTP狀態碼。表 HTTP狀態碼類別表 常用HTTP狀態碼成功創建（通過POST或PUT）LocationNO例如NOTGETDateContent-Location和EtagGETBADNOT401403INTERNAL "message":"AccountreacheditsAPIratelimit.", 建議使用Out2協議來進行用戶身份認證。Ouh2協議為用戶資源的授權提供了一個安全開放的（oke）用來代替密碼，供第三方應用使用。獲得令牌的四種授權方式為：授（auhozaone（pci（paso（centcednaatoded和EtTaEnttyaNoneMchGTTagfNoneMcTPETgfNoneMch與服務器重新計算的所請求的資源的ETg值不一致時，服務器才響應新資源。如果服務器端計算Tg值與請求頭中fNoneMch一致，說明客戶端再次發起相同請求，且所請求的網絡資源304Notoded從客戶端瀏覽器緩存中讀取。在協商緩存機制aModed（最后修改時間）中，請求時包含fModfeSnce頭信息，可以使服務器根據atModed來判斷是否再次返回資源。使用標準時間戳aodfRSTPPPNPI3.ETP（nah（eesutag（exenaDoc（coponenPeadaaPI標題、簡介、類別以及提供服務的服務商等。路徑部分為P描述文檔的主要功能部分，描述該P的TP附錄A.1A.1表A.1智慧社區跨界服務價值網絡模型元素屬性定義圖A.2為智慧社區平臺的目標分解模型。智慧社區跨界服務系統主要目的是賦能社區構建智慧社A.2A.2APPAPPAPPAPPAPPAIAIA.3給出了智慧社區平臺原子過程“保安巡查”、原子過程“現場處理”、原子過程“審查報告”、原子過程“物業審核”。A.3A.3附錄智慧社區跨界服務APIuriAPIuri，每個API都有唯一的uriAPI的接口定義。舉例：ip:port為平臺webOpenAPI包含多種應用資源集：包括視頻應用資源集，人員管控資源集，車輛管控資源5.1.1節描述的命名規范。圖B.1 "receptionistId":"123v453673dsfgef12312","visitorPermissionSet":{"defaultPrivilegeGroupFlag":"1","privilegeGroupIds":["visitStartTime":"2018-07-26T15:00:00+08:00","visitEndTime":"2018-07-26T19:00:00+08:00","visitPurpose"visitorInfoList":["visitorName":"gender":1,"phoneNo":"plateNo":"浙A12345","certificateType"certificateNo":,"certAddr":"江蘇南京","certIssuer"nation":1,"birthplace"visitorPhoto":cMc8yMjIfE87ujdq0nvyPcKodJ3XPpvt//2Q==","visitorWorkUnit":"海康威視","visitorAddress":"code":"msg":"success","data":{"appointRecordId":"123456789","appointmentInfoList":["visitorName":"張三","receptionistId":"3124126241412","receptionistName":"王五","verificationCode":"1234","QRCode":"v1256v5755","orderId":"170xd8g157t7cu8w8yvhiwr","svrIndexCode":"120d8qbvuhr8qy81bhq85fubhqvhu0438"該案例中，使用了POST從其他返回圖片Uri圖片Uri（headerLocation可以獲取到。HTTP/1.1Cache-Control:no-cachePragma:no-cacheexpires:Wed,31Dec196923:59:59GMTContent-Length:Date:Fri,28Sep201801:55:00"code":"data":"msg":"Therequiredparameterp