Contributor为Linkis贡献新的Restful接口时，需遵循如下接口规范进行接口开发。

1. HTTP or WebSocket ?

Linkis目前提供了两种接口方式：HTTP和WebSocket。

WebSocket相比于HTTP的优势：

  • 对服务器产生的压力更小
  • 信息推送更加及时
  • 交互性更加友好

相应的，WebSocket也有如下的劣势：

  • WebSocket在使用时可能出现断开连接的情况
  • 对前端的技术要求更高
  • 一般要求前端有降级处理机制

如非必要，我们通常强烈建议Contributor尽量少用WebSocket的方式提供接口；

如您觉得使用WebSocket很有必要，且愿意将开发的功能贡献给Linkis，建议您在开发前与我们取得沟通，多谢！

2. URL规范

  1. /api/rest_j/v1/{applicationName}/.+
  2. /api/rest_s/v1/{applicationName}/.+

约定：

  • rest_j表示接口符合Jersey规范
  • rest_s表示接口符合springMVC Rest规范
  • v1为服务的版本号，版本号会随着Linkis版本进行升级
  • {applicationName}为微服务名

3. 接口请求格式

  1. {
  2.      "method":"/api/rest_j/v1/entrance/execute",
  3.      "data":{},
  4.     "websocketTag":"37fcbd8b762d465a0c870684a0261c6e"  // WebSocket请求的必需参数，HTTP请求可忽略
  5. }

约定：

  • method：请求的Restful API URL。
  • data：请求的具体数据。
  • websocketTag：某一次WebSocket请求的唯一标识，后台也会带回该参数用于给前端进行识别。

4. 接口返回格式

  1. {"method":"/api/rest_j/v1/project/create","status":0, "message":"创建成功！","data":{}}

约定：

  • method：返回请求的Restful API URL，主要是websocket模式需要使用。
  • status：返回状态信息，其中：-1表示没有登录，0表示成功，1表示错误，2表示验证失败，3表示没该接口的访问权限。
  • data：返回具体的数据。
  • message：返回请求的提示信息。如果status非0时，message返回的是错误信息，其中data有可能存在stack字段，返回具体的堆栈信息。

另：根据status的不同，HTTP请求的状态码也不一样，一般情况下：

  • 当status为0时，HTTP的状态码为200
  • 当status为-1时，HTTP的状态码为401
  • 当status为1时，HTTP的状态码为400
  • 当status为2时，HTTP的状态码为412
  • 当status为3时，HTTP的状态码为403