RESTful接口设计要求 1 使用范围 本设计要求旨在基于标准的 RESTful 协议。对部分内容的使用加以约束。指导 RESTful接口的设计人员设计出相对统 -的接口。提高接口的可复用性。增强系统的扩展性。 2.参考文档 RESTfuI官方文档 HTTP官方文档 3.基本规范 3.1 命名规约 [推荐] RESTfuI 接口采用以下格式迸行命名: [协议]:[域名]1[项目代码]1[模块名称]/[版本]1[资源路径] 。模块名称可 以有多级。使用斜线(1)分开。根据项目的情况确定。 正例: https:llapi.example.comlauthlvlusers/{user_id} II 版本 V1 的查询用户列表的 API 接0 注意: 个产品无论辰端有多少个服务组成也应该只有 ARI入O, 示例中的 API 入0为: https:llapi.example.coml 3.2 域名 [推荐] 在不会引起跨域问题的前提下 应该尽量将 API 部署在专用域名之下。 正例: https:llapi.example.com 3.3 模块 [强制] 模块命名尽量采用全小写单词。如果需要连接多个单词。则采用中划线( -)。如果要把多个单词连接起来形 成-个具有描逑性的名称则使用下划线( )连接 3.4 资源路径 [强制] 资源的路径应该从根到子依次如下: Iresources}Iresource_id}l{sub_resources}l{sub FeSOUTCe_ _id}l{sub_resource property} (强制] URL 中不采用大小写混合的驼峰命名方式。尽量采用全小写单词; 如果需要连接多个单词 则采用连接 符 _ 不能出现 正例: /api task_ 吕rOUps 反例: Japi task-groups [强制] 接口路径使用资源名词而非动词。动作应由 HTTP Method 体现。资源组可以迸行逻辑嵌套 正例: POST Japi tasks 或 /apiltask_ Broups /I/tasks 表示在 id 为1的任务组下创建任务 反例: POST Japilcreate_ ta5k 接口路径中的获取复数资源的时候使接口路径中的获取复数资源的时候使用复数 正例: Japi tasks 反例: Japi task/list 3.5 请求参数 (强制] 如果有请求参数。请求参数使用小驼峰 [推荐] header中要加入一个唯 -的追踪标识符" X-Trace-ID" (Trace ID) , 用于请求的跟踪和对账。 X-Trace ID: 12324567-2896-1243-3456-426614174000 POST 请求参数放入 body 中 使用 json 绢码方式。 正例: POST http: LWWVI examp Le COm HTTP/I.1 Content-Type: applicationyjson;charset=UCF_ X-Trace ID: 12324567-2896-1243- 3456-426614174000 {"title" Itesti sUbValue [1,2,3]} 3.6 过滤信息 [推荐] 在请求时推荐使用过滤。排序和分页。`减轻服务器的负担和网络通信的数据量 1。分页参数 limit 指定每页显示的资源数量。 ffset 指定从哪里开始获取资源。 GET /apilitems ? limit= IO&offset- 20 或者使用 page 参数: GET /apilitems page= 381imit-10 2。排序参数 SOrt 指定排序的字段。 order 指定排序的方向 (升序或降序) GET 1api/iems sort=created_atgorder-desc 3。筛选参数 filter 根据特定条件筛选资源。 可以使用多个筛选参数来细化条件。 GET 1api/items filter [status ]=activegfilter [type] =premium 4。搜索参数 Search 对资源迸行搜索。 GET 1api/iems search-widget 日期范围 date_ from date to 指定日期范围进行筛选。 GET 1api/orders date From-2023-01-018date_ t0=2023-01-31 4.响应 [强制] HTTP请求的返回码是200的情况下。响应数据应该包含三个属性。状态码 (code) 信息描述 (message) , 响应数据 (data) _ 4.1 状态码 (code) [推荐] 状态码分成三类。业务逻辑错误 (1XXX) 数据验证错误 (2xxX) 和其它 3XXXI 业务逻辑错误 错误代码 错误消息 描述 1001 Inyalidoperation 请求的操作无效或未被支持 1002 ResourceNotFound 请求的资源不存在 1003 ResourceAlreadyExists 请求创建的资源已经存在。 1004 ResourcelnUse 资源正在使用中。无法执行请求的操作。 1005 PermissionDenied 用户没有足够的权限执行请求的操作。 1006 QUOtaExceeded 请求的操作导致配额超限。 1007 SericeUnavailable 服务当前不可用 可能是临时的。 1008 DependenciesFailed 请求的操作依赖于其他服务_ 而这些服务失败了 1009 PaymentRequired 请求的操作需要支付。但末捉供支付信息 数据验证错误 错误代码 错误消息 描述 2001 ValidationError 请求的数据验证失败 2002 MissingField 请求中缺少必要的字段 2003 InvalioField 请求中的字段值无效_ 2004 FieldFormatError 请求中的字段格式错误。 2005 FieldRangeError 请求中的字段值超出允许的范围。 2006 FielaLengthError 请求中的字段长度不符合要求。 2007 DuplicateEntry 请求中的数据已经存在。导致重复= 其他错误 错误代码 错误消息 描述 3001 Timeout 请求处理超时 3002 NetworkError 网络错误 如DNS查询失败或连接拒绝 3003 ContigurationError 服务配叠错误。如数据库连接失败。 3004 SystemMaintenance 系统正在维护中。暂时无法提供服务 3005 UnknownError 出现未知错误。无法确定具悴原因_ 4.2 信息描述 (message) [强制] 信息描述填写项目定义的状态值。 正例: object类型数据 Icodel 500002 "message UNKNOWNI I0ata" 4.3 响应数据 (data) [强制] array 类型数据。通过 list 字段。保证 data 的 Object 结构 正例: /1 array类型数据 Icodel 100000 Message WSUCCESSI Tdatal IZist": [] [强制1 空数组使用 [],而不是 null 正例: Icodel 100000 Message ISUCCESSI Tdatal IiOI IIrOLe_ 1d5" 反例 Icodel 100000 "message ISUCCESS I0ata" Iid"; IIFOLe_ T05" nU11 5.异步策略 RESTfuI 接口的异步策略是指在设计和实现 RESTfuL API 时采用的一种方法。它允许服务器在处理请求时不必立即返 回结果。而是可以在处理完成后通过某种机制将结果通知给客户端。这种策略适用于那些处理时间较长或者需要等待 其他操作完成的请求。如大量数据的处理 _ 远程服务的调用等。 5.1 复杂业务逻辑 在业务逻辑比较复杂 不能第 时间获取到结果的接口 建议使用异步的策略。另外设计一个查询结果的接口。或者 利用Nebhooks. 事件源 (Server-Send Event) _ Websocket等技术。 5.2 大文件上传下载 [推荐] 对于大文件的上传下载建议使用异步策略 接口快速返回。文件参与的事务分别迸行处理。在返回结果中携 带可查询迸度的接口地址。 (推荐1 文件上传成功返回文件I0; 避免暴露内部路径。 [推荐1 设计独立的文件上传和下载接口。井独立部署避免和其它服务使用相同的网关。造成其它服务的延迟。 6。说明文档 接口描述 详细解释接口的用途 包括业条场暴 处理逻辑等。例如: 此接口用于获取系统中已注册用户的基本僖息 包括用户名。年龄。性别等。以及它的处理逻辑和可能的业条场 请求头 列出必须包含的请求头信息。如 Content TyDe: application/json 用于表示请求体的格式为JSON 对于需要身份验证的接0 说明认证相关的请求头。如 Authorization: Bearer [token] 请求体 如果请求方式允许有请求体 (如POST PUT), 详细说明请求体的结构 给出请求体数据类型 并给出示例数据。例如: Iusername wtestuseri Ipassword" 01234561 响应头 [强制] 列出可能包含的响应头信息。如"Content Type: applicationljson " 表示响应体为JSON格式= 响应体&状态码 根据不同的状态码。详细说朋响应体的结构 给出成功和失败情况下的示例数据。例如。对于获取用户信息成功的响应: Iid": WUsername Wtestuserl Iagel 25, genderw Imale" 对于错误情况。给出错误返回的示例数据: WeFrori Invalid UISername passwordi 粝堰枚 数据格式 [推荐] 参数或者返回值如果有表示状态的字段 要用枚举类型定义出来。 (推荐1 时间字段以 ISO 8601格式返回 YYYY-MM-DDTHH:MM:55+08:00 [推荐] 如果时间的精度要求到毫秒级别, 使用 UNIX 时间戳。 格式 含义 YYYY 是公历中0000到9999年的十进刮数字 (连宁符〉 在字符串中实际出现两次。 是一年中从01 (1月〉到12 (12月 的月份 足 个月中从01到31的日期 'T"出现在字符串中 表示时间元秦的开始 是自午夜以来经过的完整小时数; 以00到24的两位小敬表示。 {冒号〉在字符串中实际出现两次。 足自小时开始以来的完整分钟数 从00到59的两位小数 是自分钟开始以来的完整秒数 从00到59的两位歆 {总)按字面意恩出觋在字符串中 是自第二个开始以来的完整亳秒数。以三位十进制数字表示。 是指定为乙" {UTC) 或"+"或"-"的时区偏移显, 后跟对间表达式HHmm 正例: 原时间 Updated Date: 2017-12-04T18:07:57+08 Creation Date: 2017-12 04T18:07: 44-08:00 ReBistry Expiry Date: 2018-12-04T18:07:44+08:00 换算成北京时间: Updated Date: 2017-12-05 02:07:57 Creation Date: 2017-12 05 02:07:44 ReBistry Expiry Date: 2018-12-05 02:07:44 7.安全 7.1网络环境划分 [推荐1 将网络环境划分为三种 即互联网环境。石油内部网络环境以及系统内部微隔离网络环境。接口设计人员要 依据使用环境来确定接口设计时所采用的安全策略。 互联网环境: 与外部互联的环境。 忑油内部网络环境: 中石油的内部网络。 系统内部微隔离网络环境: 使用微隔离技术为 组微服务隔离出来的独立环境。 7.2认证和授权 应使用安全的身份验证和授权机制来验证客户端的身份 并确定其是否有权访问特定的资源。 7.2.1 API [推荐] API Key通常用于简单的AP1访问控制。适用于不需要用户授权的场景。服务器根据API Key识别客户端并允 许或拒绝请求。通常没有过期时间 一旦发放 除非手动撤销 在这种需求情况下。使用 API Key 机制较为适宜。建 议在石油内部网络或者微隔离网络中使用。 7.2.2 OAuth token [推荐] OAuth Token是 -种复杂的认证机制。涉及到授权流程 设置有效期 井且可以提供更细粒度的控制。在需 要更复杂授权流程的场景建议使用OAuth Token。 建议在互联网环境或者石油内部网络环境中使用。 Key