API documentation

Read request parameters

A message definition describes request or response fields. Identify each field's type and name, then read its comments for meaning. Some documentation uses a shortened type-and-name notation without field numbers; that notation is not compilable proto3 source.

Actual proto3 fields include unique numbers, such as int64 userId = 1;. Arrays use repeated rather than a [] prefix. The excerpt below keeps the field numbers from the current CreateServerRequest definition.

The unixJSON field shown in older abbreviated examples is absent from the current CreateServerRequest. Use the current method definition to determine which fields to send.

{
  int64 userId;
  int64 adminId;
  string type;
  string name;
  string description;
  bytes serverNamesJSON;
  bytes httpJSON;
  bytes httpsJSON;
  bytes tcpJSON;
  bytes tlsJSON;
  bytes udpJSON;
  int64 webId;
  bytes reverseProxyJSON;
  []int64 serverGroupIds;
  int64 userPlanId;
}

syntax = "proto3";

message CreateServerRequest {
  int64 userId = 1;
  int64 adminId = 2;
  string type = 3;
  string name = 4;
  string description = 5;
  bytes serverNamesJSON = 8;
  bytes httpJSON = 9;
  bytes httpsJSON = 10;
  bytes tcpJSON = 11;
  bytes tlsJSON = 12;
  bytes udpJSON = 14;
  int64 webId = 15;
  bytes reverseProxyJSON = 16;
  repeated int64 serverGroupIds = 17;
  int64 userPlanId = 18;
}

Common field types

Canonical ProtoJSON writes 64-bit integers such as int64 and uint64 as decimal strings to avoid JavaScript precision loss. The HTTP examples here retain the small numeric values used in the API instructions; this does not establish full ProtoJSON conformance for every HTTP adapter. For large integers, confirm the representation accepted by your endpoint and avoid converting the value to a potentially imprecise JavaScript Number first.

int64

A signed 64-bit integer.

int32

A signed 32-bit integer.

uint64

An unsigned 64-bit integer; negative values are not valid.

uint32

An unsigned 32-bit integer; negative values are not valid.

double

A double-precision floating-point number.

float

A single-precision floating-point number.

string

Text enclosed in double quotes in JSON.

bool

A Boolean, represented as true or false in JSON without quotes.

bytes

Binary data represented as a Base64 string when transferred in JSON.

bytes and Base64

For text passed to a bytes field, encode the text as UTF-8 bytes, then encode those bytes as Base64. For a file, encode its original binary bytes directly. A bytes field in a JSON response must be Base64-decoded before its contents can be read in their original format.

For example, Hello, World becomes SGVsbG8sIFdvcmxk. To encode JSON configuration, encode the complete JSON text, not a single field. Changing whitespace or line endings also changes the resulting Base64 string.

The JSON and Base64 examples below are generated together from the current site domain, wafgo.com. Decoding the Base64 value produces the exact UTF-8 JSON text displayed here.

Hello, World
SGVsbG8sIFdvcmxk

{"name":"wafgo.com","type":"domain"}

eyJuYW1lIjoid2FmZ28uY29tIiwidHlwZSI6ImRvbWFpbiJ9

Arrays and repeated fields

In abbreviated documentation, []TYPE NAME means an array whose elements have the stated type. Actual proto3 uses repeated, and JSON uses a bracketed array. If the element type is a message, expand each element into an object with that message's fields.

The following examples illustrate three separate field types, not a complete request for one API. Send only fields defined by the method you are calling.

[]int64 serverGroupIds

An integer array such as [1, 2, 3]. Its proto3 declaration is repeated int64 serverGroupIds = FIELD_NUMBER;.

[]string types

A string array such as ["type1", "type2"].

[]ServerGroup serverGroups

An array of ServerGroup objects, each containing fields defined by ServerGroup.

{
  "serverGroupIds": [1, 2, 3],
  "types": ["type1", "type2"],
  "serverGroups": [
    {"id": 1, "name": "Group 1"},
    {"id": 2, "name": "Group 2"},
    {"id": 3, "name": "Group 3"}
  ]
}

Build the complete JSON object

Use a JSON object as the HTTP request body, with field names from the method definition and values matching their types. serverNamesJSON is a bytes field, so its value is a Base64-encoded JSON configuration string, not a directly nested array.

The example below shows the format of a create-website request. Its domain list is generated from the current site configuration. Replace IDs, website details, groups and protocol configuration with actual values. Empty strings only illustrate unset bytes; whether a field may be empty or omitted depends on the method's business validation.

{
  "userId": 35,
  "adminId": 1,
  "type": "httpProxy",
  "name": "My site",
  "description": "This is my site",
  "serverNamesJSON": "W3sibmFtZSI6IndhZmdvLmNvbSIsInR5cGUiOiJmdWxsIn1d",
  "httpJSON": "",
  "httpsJSON": "",
  "tcpJSON": "",
  "tlsJSON": "",
  "udpJSON": "",
  "webId": 0,
  "reverseProxyJSON": "",
  "serverGroupIds": [1, 3, 5],
  "userPlanId": 12
}

Nested objects

When a field's type is another message, JSON can represent it as a nested object. The addr example below illustrates the hierarchy; use the target API's message definition to determine the available fields.

A nested message and a bytes field are different types. A message field can contain an object directly; a bytes field still requires serialization followed by Base64 encoding.

{
  "name": "Site",
  "addr": {
    "protocol": "http",
    "host": "example.com",
    "portRange": "80"
  }
}

Empty parameters

When the request message has no fields, send an empty JSON object {} through the HTTP API. Do not send the quoted string "{}" instead.

message EmptyRequest {}

{}

Character encoding

WAFGO APIs use UTF-8. Encode JSON text and strings as UTF-8, including Chinese and other non-ASCII characters. When such text needs Base64 encoding, obtain its UTF-8 bytes first.

Base64 decoding returns the original bytes. Decode textual bytes as UTF-8 and then parse JSON when appropriate; treat file contents as binary data.