API profiles
An API profile describes a REST server that agents call through the api command. The profile holds the server's base URL, the headers and query parameters sent on every call, what a command may add or change, and the connection pool used.
Settings
| Field | Type | Default | Description |
|---|---|---|---|
secretsUsed | list of string | The secret names this profile's expressions read (sys.secret['NAME']). Worked out by the cloud when the profile is saved and sent with the profile to agent servers; anything sent in this field is ignored. | |
namerequired | string | The name this profile is referred to by, in agents and in other configuration. | |
doc | string | Free-text notes about this profile, for whoever maintains the configuration. | |
urlrequired | dynamic string | The base URL of this API server. | |
addPath | "can" | "cannot" | "must" | "can" | Whether command can add path to the base URL |
headers | object of string → ValueModel | Headers sent with every call, including any authentication. | |
canAddHeaders | boolean | false | Whether more headers can be added by the command. |
queryParams | object of string → ValueModel | Query parameters sent with every call | |
canAddQueryParams | boolean | false | Whether more query parameters can be added by the command. |
connectionPoolName | string | "default" | The connection pool used for calls to this server. |
The URL, the header values and the query parameter values are dynamic strings, so credentials can come from sys.secret instead of being stored in the profile.
What a command may add
The profile decides how far an api command may go beyond it. The path add setting says whether a command may add a path to the base URL, may not, or must. A path the command adds is relative: an absolute URL, or a path that steps outside the base URL with .., fails the call.
A header or query parameter the profile sets is replaced by the command's value only when the profile marks it as one a command may override; otherwise the call fails. A header or query parameter the profile does not have is added only when the profile allows commands to add headers or query parameters; otherwise the call fails. A query parameter written into the profile's URL itself can never be changed by a command.