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