Skip to main content
Version: 1.4.0

API Specification

When Contributor contributes new RESTful interfaces to Linkis, it is required to follow the following interface specifications for interface development.

1. HTTP or WebSocket ?​

Linkis currently provides two interfaces: HTTP and WebSocket.

WebSocket advantages over HTTP:

  • Less stress on the server

  • More timely information push

  • Interactivity is more friendly

Correspondingly, WebSocket has the following disadvantages:

  • The WebSocket may be disconnected while using

  • Higher technical requirements on the front end

  • It is generally required to have a front-end degradation handling mechanism

We generally strongly recommend that Contributor provide the interface using WebSocket as little as possible if not necessary;

If you think it is necessary to use WebSocket and are willing to contribute the developed functions to Linkis, we suggest you communicate with us before the development, thank you!

2. URL specification​


/api/rest_j/v1/{applicationName}/.+

/api/rest_s/v1/{applicationName}/.+

Convention :

  • rest_j indicates that the interface complies with the Jersey specification

  • REST_S indicates that the interface complies with the SpringMVC REST specification

  • v1 is the version number of the service. version number will be updated with the Linkis version

  • {applicationName} is the name of the micro-service

3. Interface request format​


{

"method":"/api/rest_j/v1/entrance/execute",

"data":{},

"WebsocketTag" : "37 fcbd8b762d465a0c870684a0261c6e" / / WebSocket requests require this parameter, HTTP requests can ignore

}

Convention :

  • method: The requested RESTful API URL.

  • data: The specific data requested.

  • WebSocketTag: The unique identity of a WebSocket request. This parameter is also returned by the back end for the front end to identify.

4. Interface response format​


{" method ":"/API/rest_j/v1 / project/create ", "status" : 0, "message" : "creating success!" ,"data":{}}

Convention :

  • method: Returns the requested RESTful API URL, mainly for the WebSocket mode.

  • status: Returns status information, where: -1 means not login, 0 means success, 1 means error, 2 means failed validation, and 3 means no access to the interface.

  • data: Returns the specific data.

  • message: Returns a prompt message for the request. If status is not 0, message will return an error message, where data may have a stack trace field, and return the specific stack information.

In addition: Different status cause different HTTP status code, under normal circumstances:

  • When status is 0, the HTTP status code is 200

  • When the status is -1, the HTTP status code is 401

  • When status is 1, the HTTP status code is 400

  • When status is 2, the HTTP status code is 412

  • When status is 3, the HTTP status code is 403