API documentation

API endpoint

Before calling an API, obtain a configured HTTP API endpoint. If you do not have one yet, enable the HTTP API and add a listening address on an API node. See “API node settings” below.

The HTTP API endpoint is different from the gRPC address and the management interface address.

To call a specific operation, append its service name and method name to the API endpoint.

API_ENDPOINT/ServiceName/MethodName

http://192.168.2.100/ServerService/createServer

API node settings

In your management interface, enable the HTTP API in the API node configuration and add a listening address for API requests. Use the protocol, host and port from that configuration.

In the node definition, restIsOn controls whether the API is enabled. restHTTPJSON and restHTTPSJSON configure the HTTP and HTTPS API addresses respectively. These are distinct from the regular node listening settings httpJSON and httpsJSON.

The links below document the node configuration fields and HTTP address structure. Apply the settings in your own management interface.

Making requests

Except for /APIAccessTokenService/getAPIAccessToken, which obtains an access token, every API request must include an X-Edge-Access-Token HTTP header. The token authenticates the caller and their permission to access the API.

Send a complete JSON request body using POST and set Content-Type: application/json. API responses also use JSON.

The example below queries access logs. Replace serverId, day, size and other parameters as needed. Replace YOUR_ACCESS_TOKEN with a valid token obtained from the authentication endpoint.

POST /HTTPAccessLogService/listHTTPAccessLogs HTTP/1.1
Host: 192.168.2.100
Content-Type: application/json
X-Edge-Access-Token: YOUR_ACCESS_TOKEN

{
  "serverId": 23,
  "day": "20210101",
  "size": 100,
  "reverse": true
}

cURL example

Replace the example IP address, port and YOUR_ACCESS_TOKEN with your own HTTP API endpoint and access token. Adjust the request data to match your query.

curl -v -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Edge-Access-Token: YOUR_ACCESS_TOKEN' \
  'http://192.168.1.6:8004/HTTPAccessLogService/listHTTPAccessLogs' \
  -d '{
    "size": 100,
    "day": "20211217"
  }'

Formatted output

Add X-Edge-Response-Pretty: on to the HTTP headers to make the response JSON easier to read.

X-Edge-Response-Pretty: on

HTTP status codes

Always check the HTTP response status code first. Only HTTP 200 indicates a successful HTTP call. This status is separate from the code field in the JSON response; neither replaces the other.

After receiving HTTP 200, inspect the business result according to the operation's response structure. For example, the token endpoint also requires the JSON code field to equal 200.

200

The HTTP call succeeded. Continue by reading and checking the operation's JSON response.

400

The request format is invalid, for example because the request is too large or the JSON is malformed.

404

The API service or method does not exist, or the request uses an incorrect API path.

Frequently asked questions

What should I do if a call reports Received HTTP/0.9 when not allowed?

First check that an HTTP API endpoint has been added to the API node and that your request uses that address. Do not substitute the gRPC or management interface address. Configure the HTTP API endpoint and try again.