设计规范

欢迎查看 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 状态码来快速判断请求状态，请求返回响应体会进一步补充详细的上下文需要的信息。

请求返回的状态码说明如下：

API 结构体规范 #

极限 API 的请求和响应默认都使用 JSON 作为数据的一种表达方式，所有请求都需要显示添加 "Content-type: application/json" Header 头信息。

对于 API 请求的结构体，没有特殊的要求，一般建议使用 JSON 来描述请求的相关信息。

对于 API 操作的响应信息，对描述请求操作状态的约定如下：

• 首先根据请求的状态码来判断是否出现异常，非 200、201 即可能存在异常。
• 请求和返回结构体基于领域对象设计模型，字段尽量精简，够描述该场景的操作即可。
• 如果请求只有两种情况，要么成功要么失败，使用布尔类型的 success 字段来进行说明。
• 如果请求不止两种情况，使用字符类型的 result 来进行描述，根据各个 API 的场景来定义常量字符，如对象增删改操作可能返回：created、updated、not_found 和 deleted。
• 如果请求是一个异步操作，使用布尔类型的 acknowledged 来描述请求是否被服务器接收。
• 如果服务端处理某个请求出错了，除了状态码和上面对应的状态字段外，还可选择性的提供可读的错误描述，使用对象类型的 error 字段来进行描述。

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
}