SPEC0001 - 基础URI规范
| 版本 | 作者 | 修订时间 | 备注 |
|---|---|---|---|
| 0.1 | Lang | 2018.02.22 | 草稿 |
1. URI基本规范
根据平台适应性本身的不同，URI按不同应用场景进行分类，并进一步简化，用于描述所有目前需要使用的URI信息，针对接口进行统一定制。
1.1. URI模式说明
URI模式主要按认证模式进行分类，主要包含以下几种：
- 开放模式：不带任何认证授权的开放性资源。
- 三方模式：开放给第三方应用获取资源的基础URI，认证模式一般使用OAuth。
- 平台模式：由平台前端访问的基础模式（一般为平台内部App或平台本身相互调用）。
- 集成模式：由平台提供给第三方合作伙伴的后端集成专用接口。
- 终端模式：由平台内部运行的App独立开发的认证模式，不同的App可使用不同的认证模式。
1.2. URI基本分类
其中v1为版本号，最终考虑使用版本流量导入模型来处理不同版本之间的升级和切换，其中{name}参数为开放的第三方系统以及开放的第三方App的名称，需注意的是：带有{name}的模式主要处理一下几种情况
/v1/open/*不满足第三方业务需求时针对特殊服务使用相关路径处理。- 采用路径适配器模型对于路径适配时可采用
{name}进行URI资源的二次调用（路径适配法则配合Api Gateway进行开发 - 如果第三方合作伙伴合作不配合程度较高时采用特殊处理，定义新接口采用
{name}路径。
| 路径前缀 | 备注 | 认证模式 |
|---|---|---|
| /v1/* | 纯开放API模式，其中v1为当前平台的版本号。 | 开放模式 |
| /v1/api/* | 平台内部前端访问的基础模式，内部App或平台本身调用 | 平台模式（需认证） |
| /v1/open/* | 由平台发布的开放性接口专用Api | 三方模式（需认证） |
| /v1/tp/{name}/* | 开放给合作伙伴的接口专用文档 | 集成模式（需认证） |
| /v1/app/{name}/* | 平台运行的App独立开发认证模式 | 终端模式（需认证） |
基本定义原则：
- 平台本身Restful为一等公民，所以平台接口全部采用
/v1的前缀，除版本以外仅分为鉴权和非鉴权模式两种。 - 针对开放性接口和第三方集成接口分开，开放性接口一般采用OAuth的认证，而和第三方系统集成时其鉴权模式会有所不同。
- 平台内部运行的App独立开发时，所有和它相关的特殊性强的路径全部位于：
/app之下，方便管理，并且带上该系统特殊的{name}进行说明。
2. Http状态应用规范
在平台内部释放Http状态代码，由不同业务场景预定义可支持的不同状态代码，并制定相关容错表和错误数据表。
2.1. Http状态含义对照表
状态含义表中仅枚举目前平台需要使用的部分，未使用部分暂不纳入考虑。
| 状态代码 | 状态描述 | 业务场景 |
|---|---|---|
| 101 | Switching Protocols | 当协议从Http切换成其他协议如WebSocket时，服务端返回相关信息，并告知客户端Upgrade消息头通知其应该切换的协议名。 |
| 102 | Processing | 当前端发起异步任务请求时，如果前端需要查询任务状态，异步任务未完成时采取该状态代码进行处理。 |
| 200 | OK | 请求成功：SUCCESS。 |
| 201 | Created | 通知客户端该资源已被创建，目前版本暂不支持Location头信息，当用户在重复请求创建某一资源时使用该状态代码进行标识，该状态需要实现HTTP的幂等性。 |
| 204 | No Content | 针对服务端有可能在返回值部分出现的空指针异常NullPointerException采用204代码通知客户端无任何响应数据，该状态代码限制开发人员考虑这种异常的专用情况，解决Java中的NullPointer常见错误。 |
| 302 | Move temporarily | 当平台版本从v1开始升级成v2过程中，禁用v1时的专用状态代码，迁移过程中提示用户该API已进入升级流程。 |
| 303 | See Other | 当平台版本升级完成后，客户端再访问v1的API时，该API有可能已经不存在，此时提供响应状态告诉客户端已经改变的API详细描述信息。 |
| 400 | Bad Request | 请求前置验证语义问题，一般处理参数验证（是否必须、类型不合法、值不合法、序列化异常）等通用性请求验证异常信息。 |
| 401 | Unauthorized | 认证异常 |
| 403 | Forbidden | 权限不足，授权异常 |
| 404 | Not Found | 资源无法找到（注意和302, 303进行区分） |
| 405 | Method Not Allowed | 通知客户端重新发送请求，并带上Allow头信息高速客户端重新发送请求的方法信息。 |
| 406 | Not Acceptable | 【响应流程处理】判断客户端Accept头信息，并根据Accept做出服务端的合适选择，如果无法处理客户端Accept中的信息，告知客户端该媒体类型无法解析，包括Accept-*类型的所有系列。 |
| 408 | Request Timeout | 用于处理两种请求：路由Api Gateway服务在查找其他服务过程中，无法在预定时间内给出合适响应，则给出408异常。服务本身在处理大数据量任务，该任务超过了服务定制的时间上限，则通知客户端超时，并提示访问该任务的状态查询地址（可返回200和102的状态检索地址信息） |
| 412 | Precondition Failed | 对于平台和应用的转发性请求过程中，如果请求未通过平台本身验证，直接发送到平台中的内部请求地址，则判定为：先决条件不满足，不予响应。 |
| 413 | Request Entity Too Large | 附件上传文件越界、数据量越界、则提供该状态代码。 |
| 415 | Unsupported Media Type | 【请求处理流程】根据客户端提供的Content-Type信息，服务端无法给出对应的解析方式，则提供415异常，包括encoding，language等所有Content-*类型的请求无法处理时专用。 |
| 421 | too many connections | 熔断、限流、服务降级时专用异常代码，不运行接收新请求。 |
| 423 | Locked | 当两个请求同时更新一条资源信息时，多用于PUT请求中，后发送的请求告诉客户端该资源被锁定。 |
| 424 | Failed Dependency | 出现第三方依赖接口错误专用异常，如服务端访问了第三方的接口，如云证、底账库、七牛等。 |
| 449 | Retry With | 一般可用于未通过认证，数据格式不合法，以及字段锁定，在允许重试的接口中使用该状态代码进行说明。 |
| 451 | Unavailable For Legal Reasons | 该请求资源具有敏感信息或法律风险导致请求不可用。 |
| 500 | Internal Server Error | 服务器内部错误，代码异常情况依靠该错误。 |
| 501 | Not Implemented | 临时接口（该接口可能处于开发过程中）。 |
| 503 | Service Unavaible | 服务临时挂掉，等待恢复时使用该状态代码进行说明。 |
2.2. 关于状态代码的选择原则
- 关于请求过程中的状态代码，优先参考非400 Bad Request部分的状态代码（404 Not Found除外），在无法抉择的情况下选择400 Bad Request部分的状态代码用于描述相关响应。
- 关于响应过程中的状态代码，优先参考非500 Internal Server Error部分的状态代码，数据本身问题可使用4XX的状态代码进行描述，基本如：第三方接口依赖性问题选择使用424，登陆需要重试可使用449 Retry With等。
- 对于基本的HTTP方法如：
GET、POST、PUT、DELETE等，优先考虑HTTP幂等性法则，以满足HTTP幂等性为前提。