• 1. HTTP or WebSocket ?
  • 2. URL规范
  • 3. 接口请求格式
  • 4. 接口返回格式

    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