跳到主要内容
版本: 最新版本-3.5

StarRocks Restful API 标准

API 格式​

  1. API 格式遵循以下模式：/api/{版本}/{目标对象访问路径}/{动作}。
  2. {版本} 表示为 v{数字}，例如 v1、v2、v3、v4 等。
  3. {目标对象访问路径} 以分层方式组织，稍后将详细说明。
  4. {动作} 是可选的，API 实现者应尽可能利用 HTTP 方法来传达操作的含义。只有当 HTTP 方法的语义无法满足时，才应使用动作。例如，如果没有可用于重命名对象的 HTTP 方法。

目标对象访问路径的定义​

  1. REST API 访问的目标对象需要分类并组织成一个分层访问路径。访问路径格式如下
/primary_categories/primary_object/secondary_categories/secondary_object/.../categories/object

以 catalog、database、table、column 为例

/catalogs: Represents all catalogs.
/catalogs/hive: Represents the specific catalog object named "hive" under the catalog category.
/catalogs/hive/databases: Represents all databases in the "hive" catalog.
/catalogs/hive/databases/tpch_100g: Represents the database named "tpch_100g" in the "hive" catalog.
/catalogs/hive/databases/tpch_100g/tables: Represents all tables in the "tpch_100g" database.
/catalogs/hive/databases/tpch_100g/tables/lineitem: Represents the tpch_100g.lineitem table.
/catalogs/hive/databases/tpch_100g/tables/lineitem/columns: Represents all columns in the tpch_100g.lineitem table.
/catalogs/hive/databases/tpch_100g/tables/lineitem/columns/l_orderkey: Represents the specific column l_orderkey in the tpch_100g.lineitem table.
  1. 类别使用 snake-case 命名，最后一个单词采用复数形式。所有单词都采用小写形式，多个单词通过下划线 (_) 连接。特定对象使用它们的实际名称命名。需要明确定义目标对象的分层关系。

HTTP 方法的选择​

  1. GET：使用 GET 方法显示单个对象并列出某个类别的所有对象。GET 方法对对象的访问是只读的，不提供请求体。
# list all of the tables in database ssb_100g
GET /api/v2/catalogs/default/databases/ssb_100g/tables

# show the table ssb_100g.lineorder
GET /api/v2/catalogs/default/databases/ssb_100g/tables/lineorder
  1. POST：用于创建对象。参数通过请求体传递。它不是幂等的。如果对象已存在，则重复创建将失败并返回错误消息。
POST /api/v2/catalogs/default/databases/ssb_100g/tables/create -d@create_customer.sql
  1. PUT：用于创建对象。参数通过请求体传递。它是幂等的。如果对象已存在，它将返回成功。PUT 方法是 POST 方法的 CREATE IF NOT EXISTS 版本。
PUT /api/v2/databases/ssb_100g/tables/create -d@create_customer.sql
  1. DELETE：用于删除对象。它不提供请求体。如果要删除的对象不存在，它将返回成功。DELETE 方法具有 DROP IF EXISTS 语义。
DELETE /api/v2/catalogs/default/databases/ssb_100g/tables/customer
  1. PATCH：用于更新对象。它提供了一个请求体，其中只包含需要修改的部分信息。
PATCH /api/v2/databases/ssb_100g/tables/customer -d '{"unique_key_constraints": ["c_custkey"]}'

身份验证和授权​

  1. 身份验证和授权信息在 HTTP 请求头中传递。

HTTP 状态码​

  1. HTTP 状态码由 REST API 返回，以指示操作的成功或失败。
  2. 成功操作的状态码 (2xx) 如下
  • 200 OK：表示请求已成功完成。它用于查看/列出/删除/更新对象和查询待处理任务的状态。
  • 201 Created：表示对象已成功创建。它用于 PUT/POST 方法。响应体必须包含对象 URI 以便后续查看/列出/删除/更新。
  • 202 Accepted：表示任务提交成功，任务处于待处理状态。响应体必须包含任务 URI 以便后续取消、删除和轮询任务状态。
  1. 错误代码 (4xx) 表示客户端错误。用户需要调整和修改 HTTP 请求并重试。
  • 400 Bad Request：无效的请求参数。
  • 401 Unauthorized：缺少身份验证信息，非法身份验证信息，身份验证失败。
  • 403 Forbidden：身份验证成功，但用户的操作未能通过授权检查。没有访问权限。
  • 404 Not Found：API URI 编码错误。它不属于已注册的 REST API。
  • 405 Method Not Allowed：使用了不正确的 HTTP 方法。
  • 406 Not Acceptable：响应格式与 Accept 标头中指定的媒体类型不匹配。
  • 415 Not Acceptable：请求内容的媒体类型与 Content-Type 标头中指定的媒体类型不匹配。
  1. 错误代码 (5xx) 表示服务器错误。用户无需修改请求，可以稍后重试。
  • 500 Internal Server Error：内部服务器错误，类似于未知错误。
  • 503 Service Unavailable：该服务暂时不可用。例如，用户的访问频率过高，已达到速率限制；或者该服务当前由于内部状态而无法提供服务，例如当创建具有 3 个副本的表时，但只有 2 个 BE 可用；用户查询中涉及的所有 Tablet 副本都不可用。

HTTP 响应格式​

  1. 当 API 返回 HTTP 代码 200/201/202 时，HTTP 响应不为空。API 以 JSON 格式返回结果，包括顶级字段“code”、“message”和“result”。所有 JSON 字段都使用驼峰式命名。

  2. 在成功的 API 响应中，“code”为“0”，“message”为“OK”，“result”包含实际结果。

{
   "code":"0",
   "message": "OK",
   "result": {....}
}
  1. 在失败的 API 响应中，“code”不为“0”，“message”是一个简单的错误消息，“result”可以包含详细的错误信息，例如错误堆栈跟踪。
{
   "code":"1",
   "message": "Analyze error",
   "result": {....}
}

参数传递​

  1. API 参数按路径、请求体、查询参数和标头的优先级顺序传递。选择合适的参数传递方法。

  2. 路径参数：表示对象分层关系的必需参数放置在路径参数中。

 /api/v2/warehouses/{warehouseName}/backends/{backendId}
 /api/v2/warehouses/ware0/backends/10027

  1. 请求体：参数使用 application/json 传递。参数可以是必需类型或可选类型。

  2. 查询参数：不允许同时使用查询参数和请求体参数。对于同一个 API，选择其中一个。如果排除标头参数和路径参数的参数数量不超过 2 个，则可以使用查询参数；否则，使用请求体传递参数。

  3. HEADER 参数：标头应用于传递 HTTP 标准参数，例如 Content-type 和 Accept 放置在标头中，实现者不应滥用 http 标头来传递自定义参数。当使用标头传递用户扩展的参数时，标头名称应采用 x-starrocks-{name} 格式，其中 name 可以包含多个英文单词，并且每个单词都小写并用连字符 (-) 连接。