This topic describes how to call open APIs of OceanBase Shell (OBShell) over HTTP. The GetObInfo API is taken as an example.
Request syntax
A complete HTTP request consists of the request URI, request method, request header, and request message body.
Request URI
A request URI consists of the following fields:
{scheme}://{endpoint}/{resource-path}?{query-string}
| Field | Description |
|---|---|
| scheme | The transmission protocol. Valid values: HTTP and HTTPS. |
| endpoint | The endpoint of the OBShell service. Example: xxx.xxx.xxx.xxx:2886. The value is determined by the OBServer node where OBShell is stored. |
| resource-path | The resource path of the API. For more information about the resource path of an API, see the Request path section in the corresponding API reference. For example, the resource path of the GetObInfo API is /api/v1/ob/info. |
| query-string | The query parameters, which are optional key-value pairs. Example: a=10&b=hello. Separate query-string and resource-path with a question mark (?). |
Here is a complete URI of a sample GetObInfo request:
http://xxx.xxx.xxx.xxx:2886/api/v1/ob/info
Request method
A request method is an HTTP method. Valid methods include GET, PUT, POST, and DELETE. The request methods of each API are described in the corresponding API reference. For example, in the request path GET /api/v1/ob/info, the request method of the API is GET.
Request header
A request header contains additional information of the request, such as the authentication information.
| Field | Required | Description | Example |
|---|---|---|---|
| Content-Type | Yes | The type of the message body. The message body of an OBShell API request is of the application/json type. |
application/json |
Authentication
For more information, see Authentication based on public-key encryption.
Response structure
OBShell APIs return data in a unified data structure, except for some special APIs. The data structure of a basic return result is as follows.
| Parameter | Type | Description |
|---|---|---|
| data | Object | Parameters of different data types. |
| error | Object | The error caused by the request. |
| successful | Boolean | Indicates whether the request is successful. |
| timestamp | Datetime | The timestamp when the server completed the request. |
| duration | Integer | The amount of time taken by the server to process the request, in milliseconds. |
| status | Integer | The HTTP status code. |
| traceId | String | The trace ID of the request. |
Example
You can use curl to call OBShell APIs. In the following example, the IP address of OBShell is xxx.xxx.xxx.xxx, the port number is 2886, and the request calls an API to remove the specified node.
curl "http://xxx.xxx.xxx.xxx:2886/api/v1/agent/remove"
-H "Content-Type: application/json"
-X POST
-H 'X-OCS-Auth:QeBJZNUvhEJ5sCCtANo6p4hm44lr+xAvN+zYpZ8OKoSl5Wsa/3DLYL8/EB/h48dT3QaTuGFgh4R1Y/jqMW4FYRRiZxk97JC+uPUVt3G4np1UIKIXk30diItIk0oq8DBTPdKQix8IE45zk+D1np7LwAHBTcr7kQsOilgQR+D9N9g='
-d '{"ip":"xxx.xxx.1","port":2886}'