API call description

This topic describes how to call an API operation of OceanBase Cloud Platform (OCP) in the HTTP mode, using the Query clusters operation as an example.

Request structure

A complete HTTP request includes a request URI, a request method , a request header , and a request body .

Request URI

A request URI consists of the following parts:

{scheme}://{endpoint}/{resource-path}?{query-string}

The following example is a complete URI of the Query clusters API:

http://xxx.xxx.xxx.xxx:8080/api/v2/ob/clusters

Request method

A request method is an HTTP method, which can be GET, PUT, POST, or DELETE. The request methods of each API are described in the corresponding API documentation.

For example, in the request path GET /api/v2/ob/clusters, the request method of the Query clusters API is GET.

Request header

A request header contains the additional information of the request, such as the language and authentication information.

Request body

The request body is optional. It contains the service data sent to the server. OCP APIs use request bodies in the unified JSON format.

Authentication description

Clients that call an OCP API can be authenticated in AK/SK or HTTP Basic authentication mode.

• HTTP Basic authentication mode

  To call an OCP API, you must pass the Base64-encoded username:password string by using the Authorization attribute in the request header.

  For example, assume that the password of user foo is bar. When user foo calls an OCP API, the following information must be passed in the request header:

  Authorization: Basic Zm9vOmJhcg==
  

  In the preceding information, Zm9vOmJhcg== is the Base64-encoded foo:bar string.

  Notice

  Password leakage may occur in HTTP Basic authentication mode. We recommend that you use the AK/SK authentication mode.

• AK/SK authentication mode (recommended)

  In AK/SK authentication mode, you do not have to pass a plaintext password in an HTTP request, and you can authorize other users to log on without sharing your password.

  For more information, see Rules for generating a signature by using AK/SK.

Response structure

OCP APIs return data in a unified data structure, except for some special APIs. Data structure of the basic return result:

Call example

cURL

You can use the cURL tool to call APIs. In the following example, the user admin:hello calls the Query tenants API of an OCP application with the IP address xxx.xxx.xxx.xxx, the port information 8080. Where, YWRtaW46aGVsbG8= is the Base64 encoding of admin:hello.

curl "http://xxx.xxx.xxx.xxx:8080/api/v2/ob/clusters/1/tenants"  \
  -H "Authorization: Basic YWRtaW46aGVsbG8="

cURL also allows you to use a plaintext password to call an API.

curl "http://xxx.xxx.xxx.xxx:8080/api/v2/ob/clusters/1/tenants"  \
  --user admin:hello

Internationalization

OCP APIs support internationalization. The API returns the content in the specified language based on the language settings of the client. You can refer to the API documentation to check whether an attribute support internationalization.

An OCP API uses the Accept-Language attribute in the request header to specify the language option of the client.

Throttling

OCP provides the throttling feature to prevent users from accessing OCP too frequently. When creating an OCP user, the system administrator can set a throttling strategy for the user. Resources subject to throttling include global paths, which include all HTTP requests except for static resources. Fine-grained access control allows you to set access limits for different types of resources in OCP. The throttling window can be set to 10s, 1 min, 1 h, and 1 day.

You can enable or disable the throttling feature by setting the ocp.iam.rate-limit.enabled system parameter. The default value is true, indicating that throttling is enabled.

When throttling is enabled, the returned header contains the following information:

1. RateLimit-Limit: The upper limit of access requests in the current time window, for example, 10.

2. RateLimit-Remaining: The number of remaining access times in the current time window, such as "7".

3. RateLimit-Reset: The countdown to the reset of the throttling time window, such as "53".

When a user accesses the corresponding resource interface exceeds the specified threshold in the time window, the request is rejected due to throttling, and the HTTP code 429 is returned. Return result:

{
    "duration":0,
    "error":{
        "code":0,
        "message":"Excessive number of requests. You have exceeded the request limit for the current throttling window."
    },
    "server":"a83ad33525",
    "status":429,
    "successful":false,
    "timestamp":"2020-12-03T09:38:24.194+08:00",
    "traceId":""
}