This topic uses the GetObInfo API operation as an example to describe how to call OceanBase Shell (OBShell) API operations over HTTP.
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 include HTTP and HTTPS. |
| endpoint | The endpoint of OBShell, for example, 10.10.10.1:2886. The value is determined by the OBServer node where OBShell is stored. |
| resource-path | The resource path of the API operation. For more information, see the Request path section in the corresponding API reference. For example, the resource path of the GetObInfo API operation is /api/v1/ob/info. |
| query-string | The query parameters, which are optional key-value pairs in the format of a=10&b=hello. query-string and resource-path must be separated with a question mark (?). |
Here is a complete URI of a sample GetObInfo request. 10.10.10.1:2886 is the endpoint of OBShell.
http://10.10.10.1:2886/api/v1/ob/info
Request methods
HTTP request methods, including GET, PUT, POST, and DELETE, are supported. The request methods of each API operation are described in the corresponding API reference. For example, in the request path GET /api/v1/ob/info, the request method of the API operation is GET.
Request header
A request header contains additional information of the request, such as the authentication information.
| Name | 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 Hybrid encryption for API operations.
Response structure
OBShell API operations return data in a unified data structure, except for some special API operations. The following table describes the data structure of a basic return result.
| Parameter | Type | Description |
|---|---|---|
| data | any | Parameters of different data types. |
| error | ApiError | The error caused by the request, which contains the following information:
|
| successful | Boolean | Indicates whether the request is successful. |
| timestamp | time.Time | 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 API operations. In the following example, the IP address of OBShell is 10.10.10.1, the port number is 2886, and the request calls an API operation to remove the specified node. ${encrypted_header} indicates the encrypted header, and ${encrypted_body} indicates the encrypted request body. For more information about how to generate the encrypted content, see Hybrid encryption for API operations.
curl "http://xxx.xxx.xxx.xxx:2886/api/v1/agent/remove"
-H "Content-Type: application/json"
-H 'X-OCS-Header:${encrypted_header}'
-X POST
-d '${encrypted_body}'