设计规范
欢迎查看 API 文档,您可以使用 API 很灵活地对平台各个组件提供的各项能力进行完整的管理。
API 命名规范 #
极限 API 的命名设计规范参考主流开源项目( 如:Elasticsearch )的最佳实践,约定如下:
- 数据结构使用 JSON 来表达。
- 复杂对象优先使用层级的 JSON 对象,而不是扁平化的字段。
- 字段名称使用小写,使用
-
来连接对象,如:region-a
。 - 复杂对象名称或者需要增加前缀的场景,由多个字符组成的,使用
_
来进行连接,如:region-a_ip-summary
。 - 尽量使用完整的名称而不是缩写,如:使用
acknowledged
而不是ack
,使用description
而不是desc
,使用elasticsearch
而不是es
。
API URI 规范 #
极限搜索 API 遵照标准的 RESTful 规范,约定如下:
- 增: POST :resource_category/:resource_name/:resource_id
- 删: DELETE :resource_category/:resource_name/:resource_id
- 改: DELETE :resource_category/:resource_name/:resource_id
- 取: GET :resource_category/:resource_name/:resource_id
- 查: POST/GET :resource_category/:resource_name/_search
对于 URI 无法满足功能描述的场景,可以在请求体里面附加 JSON 格式的请求体来描述更多信息。
在 URI 里面出现以 _
开头的请求一般为特殊场景,表示某类操作行为的,如:_search
用来描述检索场景,或表示特殊的系统保留参数,_doc
用来描述文档场景。
API 状态码规范 #
极限 API 使用标准的 HTTP 状态码来快速判断请求状态,请求返回响应体会进一步补充详细的上下文需要的信息。
请求返回的状态码说明如下:
状态码 | 说明 |
---|---|
200 | 通用的表示操作执行成功的状态 |
201 | 创建成功,主要用于创建对象的场景 |
202 | 服务端已接收请求,可能是异步操作,不确保最终成功 |
400 | 参数有误 |
401 | 需要授权 |
403 | 身份不合法 |
404 | 资源不存在 |
405 | 请求类型错误 |
408 | 请求超时 |
409 | 请求冲突 |
413 | 请求数据超限 |
429 | 请求太频繁 |
500 | 服务端异常 |
501 | 服务端未实现该功能 |
502 | 服务端后端转发失败 |
503 | 服务端过载 |
504 | 服务端后端处理超时 |
509 | 服务端带宽超限 |
API 结构体规范 #
极限 API 的请求和响应默认都使用 JSON 作为数据的一种表达方式,所有请求都需要显示添加 "Content-type: application/json"
Header 头信息。
对于 API 请求的结构体,没有特殊的要求,一般建议使用 JSON 来描述请求的相关信息。
对于 API 操作的响应信息,对描述请求操作状态的约定如下:
- 首先根据请求的状态码来判断是否出现异常,非 200、201 即可能存在异常。
- 请求和返回结构体基于领域对象设计模型,字段尽量精简,够描述该场景的操作即可。
- 如果请求只有两种情况,要么成功要么失败,使用布尔类型的
success
字段来进行说明。 - 如果请求不止两种情况,使用字符类型的
result
来进行描述,根据各个 API 的场景来定义常量字符,如对象增删改操作可能返回:created
、updated
、not_found
和deleted
。 - 如果请求是一个异步操作,使用布尔类型的
acknowledged
来描述请求是否被服务器接收。 - 如果服务端处理某个请求出错了,除了状态码和上面对应的状态字段外,还可选择性的提供可读的错误描述,使用对象类型的
error
字段来进行描述。
字段 | 类型 | 说明 |
---|---|---|
success | bool | 描述只有两种请求返回情况的场景 |
acknowledged | bool | 提交异步操作,描述是否成功提交到服务器场景 |
found | bool | 通过 ID 来获取资源的场景,描述资源是否存在 |
result | string | 多种操作处理结果可能存在的场景,常量字符,不同业务场景的 API 可分开定义 |
error | object | 服务端错误返回,描述错误的具体信息,子对象字段 type 描述类型,reason 描述错误原因,root_cause 描述错误堆栈细节,status 描述错误状态码。 |
timed_out | bool | 描述请求是否超时 |
took | float | 描述请求执行时间 |
hits | object | 检索场景,描述请求返回的具体数据,包含两部分,total 描述请求的条数,hits 描述数组类型的结果。 |
_* | string | 如未加特殊说明,以 _ 开头的字段都为元数据字段,具有特定的上下文意义, 如 _id 用来描述某个对象或者文档的 ID,_source 描述文档的原始内容。 |
API 示例代码 #
创建请求示例
POST medcl/_doc/1
{
"name":1
}
创建成功响应示例
{
"_id":"1",
"result" : "created"
}
通过 ID 获取资源示例
GET medcl/_doc/3
获取文档失败响应示例
{
"_id":"3",
"found" : false
}
获取文档失败响应示例
{
"_id":"1",
"found" : true,
"_source" : {
"name" : "1"
}
}
检索场景请求示例
GET medcl/_search
{
"query": {
"match": {
"FIELD": "TEXT"
}
}
}
检索响应示例
{
"took" : 0,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 1,
"relation" : "eq"
},
"max_score" : 1.0,
"hits" : [
{
"_index" : "medcl",
"_type" : "_doc",
"_id" : "1",
"_score" : 1.0,
"_source" : {
"name" : "1"
}
}
]
}
}
错误响应示例
{
"error" : {
"root_cause" : [
{
"type" : "mapper_parsing_exception",
"reason" : "failed to parse field [name] of type [long] in document with id '1'. Preview of field's value: '1d'"
}
],
"type" : "mapper_parsing_exception",
"reason" : "failed to parse field [name] of type [long] in document with id '1'. Preview of field's value: '1d'",
"caused_by" : {
"type" : "illegal_argument_exception",
"reason" : "For input string: \"1d\""
}
},
"status" : 400
}