Getting started

Performing requests

• Instantiate a protobuf message called ClientRequest.
• Initiate a POST request to the /exec endpoint, including the serialized message in the request body. Set the content type to application/x-protobuf.
• Deserialize the response body into a ServerResponse protobuf message.
• Examine the error field within the response to identify potential server errors.

Requests

All requests are sent to the /exec endpoint. Each request is a protobuf message of ClientRequest type.

ca2.ClientRequest

message ClientRequest {
  bytes trx = 1;
  string token = 2;
  ca2auth.Request auth = 11;
  ca2billing.Request billing = 16;
  ca2instances.Request instances = 17;
  ca2referrals.Request referrals = 14;
  ca2servers.Request servers = 15;
  ca2ssh.Request ssh = 13;
  ca2users.Request users = 12;
  ca2utils.Request utils = 10;
  ca2domains.Request domains = 18;
}

Each response is a protobuf message of ServerResponse type.

ca2.ServerResponse

message ServerResponse {
  bytes trx = 1;
  repeated ca2.ServerError errors = 2;
  ca2auth.Response auth = 11;
  ca2billing.Response billing = 16;
  ca2instances.Response instances = 17;
  ca2referrals.Response referrals = 14;
  ca2servers.Response servers = 15;
  ca2ssh.Response ssh = 13;
  ca2users.Response users = 12;
  ca2utils.Response utils = 10;
  ca2domains.Response domains = 18;
}

ca2.ServerError

enum ServerError {
  SE_UNKNOWN_ERROR = 0;
  SE_TRX_REQUIRED_ERROR = 1;
  SE_INVALID_TRX_ERROR = 2;
  SE_INVALID_TOKEN_ERROR = 4;
  SE_EXPIRED_TOKEN_ERROR = 5;
  SE_INTERNAL_SERVER_ERROR = 6;
  SE_TOKEN_REQUIRED_ERROR = 7;
  SE_RATE_LIMIT_EXCEEDED_ERROR = 8;
}

See API reference for more information.

WebSockets

The WebSocket is available at the /ws endpoint. After connecting to the WebSocket, the client should send a WsAuth message to the server:

ca2.WsAuth

message WsAuth {
  string token = 2;
}

After the server receives the WsAuth message with a valid token, it will immediately send empty WsEvent message. Next on every event, the server will send a WsEvent message with the data.

Client can break the connection every time.

When client is offline, all events are lost. The server does not store any events. So after the client reconnects, it should request the missing data with the synchronous requests.

sequenceDiagram
    participant Client
    participant Server
    Client->>+Server: Create WebSocket connection
    Client->>+Server: WsAuth (with token)
    Server->>+Client: WsEvent (empty)
    loop
        Server->>+Client: WsEvent (with data)
    end
    Client->>+Server: Break connection

Errors on WebSocket

In case of an error (e.g. invalid token), the WsEvent message contains ServerErrors same as in the synchronous requests.

ca2.ServerError

enum ServerError {
  SE_UNKNOWN_ERROR = 0;
  SE_TRX_REQUIRED_ERROR = 1;
  SE_INVALID_TRX_ERROR = 2;
  SE_INVALID_TOKEN_ERROR = 4;
  SE_EXPIRED_TOKEN_ERROR = 5;
  SE_INTERNAL_SERVER_ERROR = 6;
  SE_TOKEN_REQUIRED_ERROR = 7;
  SE_RATE_LIMIT_EXCEEDED_ERROR = 8;
}

After sending the WsEvent message with errors, the server will break the connection.

sequenceDiagram
    participant Client
    participant Server
    Client->>+Server: Create WebSocket connection
    Client->>+Server: WsAuth (with token)
    Server->>+Client: WsEvent (with errors)
    Server->>+Client: Break connection

Ws Events

ca2.WsEvent

message WsEvent {
  repeated ca2.ServerError errors = 2;
  ca2billing.WsEvent billing = 1;
  ca2instances.WsEvent instances = 3;
  ca2domains.DomainCheckWsEvent domain_check = 4;
  ca2domains.DomainEvent domains = 5;
}

ca2billing.WsEvent

message WsEvent {
  repeated ca2types.Balance balances = 1;
  repeated ca2types.Payment payments = 2;
}

ca2instances.WsEvent

message WsEvent {
  repeated ca2types.Instance updated_instances = 1;
}