2024智慧社区跨界服务需求建模与设计规范

前 引 范 基于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