API Reference

Authentication

With the notable exception of the authentication API calls (e.g. Login or GetToken), each API call must be authenticated. Authentication is performed using gRPC metadata when using the gRPC API, and HTTP Headers when using the REST API. There are two types of clients for the Panto API: Agents and Users. This documentation explains how to set up the credentials in your API call in each case.

Agent authentication

Agent authentication is set-up automatically from the agent configuration. An agent authenticates using its API name as a Bearer token. The token is set from the configuration of panto-agent at launch time, from a configuration file, command-line arguments or environment variables.

panto-agent --name=organizations/xCM3-ZaGQoOAaJbqQjcexg/agents/IPh0ffZcTV6FbwaEUR2ZhQ rpc.panto.app

If the agent name is found in the configuration database on the server, the agent will be authenticated.

User authentication

“User authentication” describes all cases where API calls are performed on behalf of an actual user, registered in the database. This concerns all requests performed from a browser running the Panto frontend client, curl calls, automation scripts, etc. Since most of these cases go through the REST API, the examples will show authentication using HTTP/1.1 headers.

Logging in

To be authenticated, a user must first Log In. The Login RPC or the login endpoint should be used. Logging in takes user credentials in the form of a username and a password. Upon successful login, a user session is created on server with a temporary API token, bound to the session. The token will be used to authenticate all further calls.

Login request:

POST /v1/login HTTP/1.1
Accept: application/json, */*
Content-Length: 62
Content-Type: application/json
Host: api.panto.app

{
    "username": "hello@world.io"
    "password": "helloworld",
}
HTTP/1.1 200 OK
Content-Length: 95
Content-Type: application/json
Date: Mon, 16 Dec 2019 12:23:12 GMT
Set-Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a; Expires=Tue, 17 Dec 2019 12:23:12 UTC; HttpOnly; Secure

{
    "expires": "2019-12-17T12:23:12.132396Z",
    "token": "djSbTqvOzGAa9kJH3hUU1rpmD4UmtyLgrrOm-L_h6l4"
}

The response contains 3 pieces of useful information:

  • The token which will be used to authenticate all further requests in the session
  • The expiration date for the session
  • The session ID in a HttpOnly cookie

Given the sensitive nature of this data, it is highly recommended to only perform these calls over a secure connection.

Authenticated API calls

Performing an authenticated call requires:

  • the session token inthe Authorization header
  • the session’s ID in the Cookie header (automatically handled by the browser)

List organizations request:

GET /v1/organizations HTTP/1.1
Accept: */*
Authorization: Bearer djSbTqvOzGAa9kJH3hUU1rpmD4UmtyLgrrOm-L_h6l4
Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a
Host: api.panto.app

List organizations response:

HTTP/1.1 200 OK
Content-Length: 118
Content-Type: application/json
Date: Mon, 16 Dec 2019 12:24:26 GMT
Set-Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a; Expires=Tue, 17 Dec 2019 12:24:26 UTC; HttpOnly; Secure

{
    "next_page_token": "",
    "organizations": [
        {
            "display_name": "Organization",
            "name": "organizations/xCM3-ZaGQoOAaJbqQjcexg"
        }
    ]
}

Note that the session is refreshed and expiration date is extended after each call. Sessions only time out after a pre-set period of inactivity.

Token retrieval

A session token is a sensitive credential and must not be stored in LocalStorage or SessionStorage, to prevent XSS attacks. therefore, a way to retrieve a lost token is available, through the GetToken RPC or the token REST endpoint. The method uses the session ID in the secure cookie to retrieve the session token.

Get token request:

GET /v1/token HTTP/1.1
Accept: */*
Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a
Host: api.panto.app

Get token response:

HTTP/1.1 200 OK
Content-Length: 95
Content-Type: application/json
Date: Mon, 16 Dec 2019 13:07:38 GMT
Set-Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a; Expires=Tue, 17 Dec 2019 13:07:38 UTC; HttpOnly; Secure

{
    "expires": "2019-12-17T13:07:38.150801Z",
    "token": "djSbTqvOzGAa9kJH3hUU1rpmD4UmtyLgrrOm-L_h6l4"
}

Login request parameters

Name Type Description / Example
username string A unique identifier for the user, in the form of a user’s email address
password string A password for the user, in plaintext

GetToken request parameters

None.

A valid session ID must be set as a SessionID cookie.

Response fields

Name Type Description / Example
token string An opaque token, bound to the newly created session, used for further authentication of the user
expires timestamp The date of expiration of the session, if no activity occurs until then

Organization

Fields

Name Type Description / Example
name string organization/ODEwMzAwMjktYzQ1ZS00OT - the “basename” of the organization is the base64-encoded UUID (without padding)
uuid bytes a 16-byte UUID
display_name string Pantomath - a name for the organization - can be used as a “user-friendly” display name in the Web UI

Methods

  • ListOrganizations(ListOrganizationsRequest) -> (ListOrganizationsResponse)
    • ListOrganizationsRequest
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListOrganizationsResponse
      • organizations - repeated Organization
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations
    • Use cases:
      • a user wants to list all organizations from the Web UI
  • GetOrganization(GetOrganizationRequest) -> (Organization)
    • GetOrganizationRequest
      • name : the relative resource name of the organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
    • GET /v1/organizations/<name>
    • Use cases:
      • a user wants to see an organization from the Web UI
  • CreateOrganization(CreateOrganizationRequest) -> (Organization)
    • CreateOrganizationRequest
      • organization : the Organization to create, excluding name and uuid which will be generated by the server
    • POST /v1/organizations
    • Use cases:
      • A user wants to create an organization from the Web UI
  • UpdateOrganization(UpdateOrganizationRequest) -> (Organization)
    • UpdateOrganizationRequest
      • organization (mandatory): an Organization containing the fields to update
      • update_mask: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • PUT /v1/organizations
    • Use cases:
      • A user wants to update an organization from the Web UI
  • DeleteOrganization(DeleteOrganizationRequest) -> ()
    • DeleteOrganizationRequest
      • name
    • DELETE /v1/organizations/<name>
    • Use cases:
      • A user wants to remove an obsolete organization from the Web UI

Agent

Fields

Name Type Description / Example
name string organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw - the “basename” of the agent is the base64-encoded UUID (without padding)
uuid bytes a 16-byte UUID
display_name string agent.pantomath.io - a “user-friendly” display name in the Web UI - recommended to use a FQDN for the agent
last_activity timestamp Timestamp of the last time the agent connected on the server

Methods

  • ListAgents(ListAgentsRequest) -> (ListAgentsResponse)
    • ListAgentsRequest
      • parent (mandatory): the relative resource name of the parent Organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListAgentsResponse
      • agents - repeated Agent
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations/<parent>/agents
    • Use cases:
      • a user wants to list all agents from the Web UI
  • GetAgent(GetAgentRequest) -> (Agent)
    • GetAgentRequest
      • name : the relative resource name of the agent, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw
    • GET /v1/organizations/<parent>/agents/<name>
    • Use cases:
      • a user wants to see an agent from the Web UI
  • CreateAgent(CreateAgentRequest) -> (Agent)
    • CreateAgentRequest
      • agent : the Agent to create, excluding name, uuid and last_activity which will be generated by the server
    • POST /v1/organizations/<parent>/agents
    • Use cases:
      • A user wants to create an agent from the Web UI
      • A new agent wants to register to the server
  • UpdateAgent(UpdateAgentRequest) -> (Agent)
    • UpdateAgentRequest
      • agent (mandatory): an Agent containing the fields to update
      • update_mask : FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • PUT /v1/organizations/<parent>/agents
    • Use cases:
      • A user wants to update an agent from the Web UI
      • An agent wants to update its own address
  • DeleteAgent(DeleteAgentRequest) -> ()
    • DeleteAgentRequest
      • name
    • DELETE /v1/organizations/<parent>/agents/<name>
    • Use cases:
      • A user wants to remove an obsolete agent from the Web UI

Check

Fields

Name Type Description / Example
name string organizations/ODEwMzAwMjktYzQ1ZS00OT/checks/qq4ugtA8Eee0yBQQn9hOqw - the “basename” of the check is the base64-encoded UUID (without padding)
uuid bytes a 16-byte UUID
target string The relative resource name of a Target
probe string The relative resource name of a Probe
type string Type of state ({threshold, trend, history}) must be provided along with configuration
configuration string Values used in combination with the state_definition (JSON object) must be provided along with type
children Object The nested children from a ListChecksRequest or a GetCheck’s children_mask field.
children.target Target The Target on which the Probe is applied
children.probe Probe The Probe on which the Target is applied

Methods

  • ListChecks(ListChecksRequest) -> (ListChecksResponse)
    • ListChecksRequest
      • parent (mandatory): the relative resource name of the parent Organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • target: optional constraint (should be a series of relative resource names of Target)
      • probe: optional constraint (should be a series of relative resource names of Probe)
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned Checks, e.g. target, probe. Leave empty for no nested resources.
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListChecksResponse
      • checks - repeated Check
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations/<parent>/checks
    • Use cases:
      • a user wants to list all checks from the Web UI
  • GetCheck(GetCheckRequest) -> (Check)
    • GetChecktRequest
      • name: the relative resource name of the check, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/checks/qq4ugtA8Eee0yBQQn9hOqw
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned Check, e.g. target, probe. Leave empty for no nested resources.
    • GET /v1/organizations/<parent>/checks/<name>
    • Use cases:
      • a user wants to see a check from the Web UI
  • CreateCheck(CreateCheckRequest) -> (Check)
    • CreateCheckRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • check: the Check to create, excluding name and uuid which will be generated by the server
    • POST /v1/organizations/<parent>/checks
    • Use cases:
      • A user wants to create a check from the Web UI
  • UpdateCheck(UpdateCheckRequest) -> (Check)
    • UpdateCheckRequest
      • check (mandatory): an Check containing the fields to update
      • update_mask: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • PUT /v1/organizations/<parent>/checks
    • Use cases:
      • A user wants to update a check from the Web UI
  • DeleteCheck(DeleteCheckRequest) -> ()
    • DeleteCheckRequest
      • name: the relative resource name of the check, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/checks/qq4ugtA8Eee0yBQQn9hOqw
    • DELETE /v1/organizations/<parent>/checks/<name>
    • Use cases:
      • A user wants to remove an obsolete check from the Web UI

ProbeConfiguration

Fields

Name Type Description / Example
name string organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw/probeconfigurations/j7e5DMTaRAGZzfpkZpdHVw - the “basename” of the configuration is the base64-encoded UUID (without padding)
check string The relative resource name of a Check
target Target The relative resource Target
configuration string A JSON string of the parameters to give to the probe
schedule Duration The period between executions of the probe

Methods

  • ListProbeConfigurations(ListProbeConfigurationsRequest) -> (ListProbeConfigurationsResponse)
    • ListProbeConfigurationsRequest
      • parent (mandatory): the relative resource name of the parent agent, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw
      • with_target: flag to include the target field in the response
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListProbeConfigurationsResponse
      • probeconfigurations - repeated ProbeConfiguration
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations/<parent>/agents/<parent>/probeconfigurations
    • Use cases:
      • An agent needs its configuration at startup
      • An agent needs to update its configuration from the server
      • a user wants to list all the ProbeConfigurations of a specific Agent from the Web UI
  • GetProbeConfiguration(GetProbeConfigurationRequest) -> (ProbeConfiguration)
    • GetProbeConfigurationRequest
      • name (mandatory) : the relative resource name of the probe configuration, e.g. organizations/<parent>/agents/qq4ugtA8Eee0yBQQn9hOqw/probeconfigurations/j7e5DMTaRAGZzfpkZpdHVw
      • with_target: flag to include the target field in the response
    • GET /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
    • Use cases:
      • a user wants to see a ProbeConfiguration of a specific Agent for a specific Probe applied to a specific Target in the Web UI
  • CreateProbeConfiguration(CreateProbeConfigurationRequest) -> (ProbeConfiguration)
    • CreateProbeConfigurationRequest
      • parent (mandatory): the relative resource name of the parent agent
      • probeconfiguration: the ProbeConfiguration to create, excluding name which will be generated by the server
    • POST /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
    • Use cases:
      • a user wants to add a ProbeConfiguration for a specific Probe applied to a specific Target by a specific Agent in the Web UI
  • UpdateProbeConfiguration(UpdateProbeConfigurationRequest) -> (ProbeConfiguration)
    • UpdateProbeConfigurationRequest
      • probeconfiguration (mandatory): a ProbeConfiguration containing the fields to update
      • update_mask : FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • PUT /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
    • Use cases:
      • a user wants to modify a ProbeConfiguration for a specific Probe applied to a specific Target by a specific Agent in the Web UI
  • DeleteProbeConfiguration(DeleteProbeConfigurationRequest) -> ()
    • DeleteProbeConfigurationRequest
      • name (mandatory)
    • DELETE /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
    • Use cases:
      • a user wants to remove a ProbeConfiguration for a specific Probe applied to a specific Target from a specific Agent in the Web UI

Target

Fields

Name Type Description / Example
name string organizations/ODEwMzAwMjktYzQ1ZS00OT/targets/GNXPRsSwTUOhz5R2BjfrAQ - the “basename” of the agent is the base64-encoded UUID (without padding)
uuid bytes a 16-byte UUID
address string target.pantomath.io - a FQDN for the target - can be used as a “user-friendly” display name in the Web UI
note string Free note for the target
tags repeated Tag Associated Tag basenames

Methods

  • ListTargets(ListTargetsRequest) -> (ListTargetsResponse)
    • ListTargetsRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListTargetsResponse
      • targets - repeated Target
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations/<parent>/targets
    • Use cases:
      • a user wants to list all targets from the Web UI
  • GetTarget(GetTargetRequest) -> (Target)
    • GetTargetRequest
      • name : the relative resource name of the target, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/targets/GNXPRsSwTUOhz5R2BjfrAQ
    • GET /v1/organizations/<parent>/targets/<name>
    • Use cases:
      • a user wants to see a target from the Web UI
  • CreateTarget(CreateTargetRequest) -> (Target)
    • CreateTargetRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • target : the Target to create, excluding name and uuid which will be generated by the server
    • POST /v1/organizations/<parent>/targets
    • Use cases:
      • A user wants to create a target from the Web UI
      • An automated deployment of a new server wants to create a new target using curl
  • UpdateTarget(UpdateTargetRequest) -> (Target)
    • UpdateTargetRequest
      • target (mandatory): the Target containing the fields to update
      • update_mask : FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • POST /v1/organizations/<parent>/targets
    • Use cases:
      • A user wants to create a target from the Web UI
      • An automated deployment of a new server wants to create a new target using curl
  • DeleteTarget(DeleteTargetRequest) -> ()
    • DeleteTargetRequest
      • name : the relative resource name of the target
    • DELETE /v1/organizations/<parent>/targets/<name>
    • Use cases:
      • A user wants to remove an obsolete target from the Web UI
      • An automated shutdown of a new server wants to destroy its target using curl

Probe

A Probe is a description of a probe in the system. It contains a unique name for the probe, and

Fields

Name Type Description / Example
name string probes/ping - since probes should be uniquely recognizable by their name, so that the agent knows which one to create, we can use this name as unique identifier
probe_name string ping - the unique short name of the probe, identical to the basename of name, used by the agent to find in the registry
display_name string Ping - A user-friendly name to be displayed in user-facing text
description string A user-friendly description of the probe, to be shown to users, e.g. when selecting a probe, or reading contextual help
configuration_template repeated ProbeParameter the list of parameters to configure this probe
metrics repeated Metric the list of metrics returned by this probe
graphs repeated Graph the list of graphs to render this probe

Methods

  • ListProbes(ListProbesRequest) -> (ListProbesResponse)
    • ListProbesRequest
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListProbesResponse
      • probes - repeated Probe
      • next_page_token, page_token to be used to get the next page
    • GET /v1/probes
    • Use cases:
      • a user wants to create or update a ProbeConfiguration in the Web UI, the client needs to fetch all the Probe descriptions to display (e.g. as a drop-down probe list)
  • GetProbe(GetProbeRequest) -> (Probe)
    • GetProbeRequest
      • name : the relative resource name of the probe, e.g. probes/ping
    • GET /v1/targets/<name>
    • Use cases:
      • a user wants to create or update a ProbeConfiguration in the Web UI, the client needs to fetch the Probe description to display options

ProbeParameter

Fields

Name Type Description / Example
name string The name of the parameter, used as key in a JSON
type string A Protobuf well-known type, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf
description string The plain text description of the probe parameter
mandatory bool Whether the ProbeParameter is mandatory or not

Alert

Fields

Name Type Description / Example
name string organizations/ODEwMzAwMjktYzQ1ZS00OT/alerts/JnsWcAb3R72wkLX_tAbQFQ - the “basename” of the alert is the base64-encoded UUID (without padding)
checks repeated string The relative resource name of the Check the alert is linked to
channel string The relative resource name of the Channel
type string Type of alert
configuration string Configuration parameters (JSON string)
children Object The nested children from a ListAlertsRequest or a GetAlert’s children_mask field.
children.checks repeated Check The list of Check on which the Alert is linked to

Methods

  • ListAlerts(ListAlertsRequest) -> (ListAlertsResponse)
    • ListAlertsRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned Alerts, e.g. checks. Leave empty for no nested resources.
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListAlertsResponse
      • alerts - repeated Alert
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations/<parent>/alerts
    • Use cases:
      • a user wants to list all the Alerts of a specific Organization from the Web UI
  • GetAlert(GetAlertRequest) -> (Alert)
    • GetAlertRequest
      • name (mandatory) : the relative resource name of the alert, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/alerts/JnsWcAb3R72wkLX_tAbQFQ
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned Alerts, e.g. checks. Leave empty for no nested resources.
    • GET /v1/organizations/<parent>/alerts/<name>
    • Use cases:
      • a user wants to see an Alert of a specific Organization in the Web UI
  • CreateAlert(CreateAlertRequest) -> (Alert)
    • CreateAlertRequest
      • parent (mandatory): the relative resource name of the parent organization
      • alert: the Alert to create, excluding name which will be generated by the server
    • POST /v1/organizations/<parent>/alerts
    • Use cases:
      • a user wants to add an Alert link to Checks in the Web UI
  • UpdateAlert(UpdateAlertRequest) -> (Alert)
    • UpdateAlertRequest
      • alert (mandatory): an Alert containing the fields to update
      • update_mask : FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • PUT /v1/organizations/<parent>/alerts/<name>
    • Use cases:
      • a user wants to modify an Alert link to Checks in the Web UI
  • DeleteAlert(DeleteAlertRequest) -> ()
    • DeleteAlertRequest
      • name (mandatory)
    • DELETE /v1/organizations/<parent>/alerts/<name>
    • Use cases:
      • a user wants to remove an Alert in the Web UI

ChannelType

Fields

Name Type Description / Example
name string channeltypes/email - the “basename” of the channeltype is the label
label string Label of channeltype
configuration repeated Parameter Available configuration parameters

Methods

  • ListChannelTypes(ListChannelTypesRequest) -> (ListChannelTypesResponse)
    • ListChannelTypesRequest
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListChannelTypesResponse
      • channeltypes - repeated ChannelType
      • next_page_token, page_token to be used to get the next page
    • GET /v1/channeltypes
    • Use cases:
      • a user wants to list all the ChannelTypes before creating a Channel from the Web UI
  • GetChannelType(GetChannelTypeRequest) -> (ChannelType)
    • GetChannelTypeRequest
      • name (mandatory) : the relative resource name of the ChannelType, e.g. channeltypes/Q3qK6T0cTsSOf4RlRz8qRw
    • GET /v1/channeltypes/<name>
    • Use cases:
      • a user wants to see a ChannelType in the Web UI

Channel

Fields

Name Type Description / Example
name string organizations/ODEwMzAwMjktYzQ1ZS00OT/channels/Q3qK6T0cTsSOf4RlRz8qRw - the “basename” of the channel is the base64-encoded UUID (without padding)
channel_type string The “basename” of the channeltype
configuration string Configuration parameters (JSON string)
children Object The nested children from a ListChannelsRequest or a GetChannel’s children_mask field.
children.channel_type ChannelType The Target on which the Probe is applied

Methods

  • ListChannels(ListChannelsRequest) -> (ListChannelsResponse)
    • ListChannelsRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned Channels, e.g. channel_type. Leave empty for no nested resources.
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListChannelsResponse
      • channels - repeated Channel
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations/<parent>/channels
    • Use cases:
      • a user wants to list all the Channels of a specific Organization from the Web UI
  • GetChannel(GetChannelRequest) -> (Channel)
    • GetChannelRequest
      • name (mandatory) : the relative resource name of the alert, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/channels/Q3qK6T0cTsSOf4RlRz8qRw
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned Channels, e.g. channel_type. Leave empty for no nested resources.
    • GET /v1/organizations/<parent>/channels/<name>
    • Use cases:
      • a user wants to see an Channel of a specific Organization in the Web UI
  • CreateChannel(CreateChannelRequest) -> (Channel)
    • CreateChannelRequest
      • parent (mandatory): the relative resource name of the parent organization
      • channel: the Channel to create, excluding name which will be generated by the server
    • POST /v1/organizations/<parent>/channels
    • Use cases:
      • a user wants to add an Channel link to Checks in the Web UI
  • UpdateChannel(UpdateChannelRequest) -> (Channel)
    • UpdateChannelRequest
      • channel : an Channel containing the fields to update
      • update_mask : FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • PUT /v1/organizations/<parent>/channels/<name>
    • Use cases:
      • a user wants to modify a Channel in the Web UI
  • DeleteChannel(DeleteChannelRequest) -> ()
    • DeleteChannelRequest
      • name (mandatory)
    • DELETE /v1/organizations/<parent>/channels/<name>
    • Use cases:
      • a user wants to remove an Channel in the Web UI

Result

Fields

Name Type Description / Example
check string The relative resource name of the Check that this resulted from
agent string The relative resource name of an Agent
probe_configuration string The relative resource name of a ProbeConfiguration
timestamp Timestamp The time at which the probe was executed. The time is always localized to UTC coordinates.
fields map<string, Any> The fields measured by the probe
tags map<string, string> The string tags associated with this result
error bool true if the probe execution encountered an error
error_message string Detailed message about the error that occured

Result has no name, as it would be much too complex to give and keep unique names for each datapoint, and probably not very useful. Clients should perform queries, and deal with the results client-side.

Methods

  • QueryResults(QueryResultsRequest) -> (QueryResultsResponse)
    • Why use a custom method instead of ListResults?
      • Fields are not a standard “named” resource
      • Most of the parameters could not be encoded in an URL query, or not easily
    • QueryResultsRequest
      • check - the relative resource name of the Check
      • agent - the relative resource name of the Agent
      • start_time - no results with a timestamp before this will be returned, beginning of time if missing
      • end_time - no results with a timestamp after this will be returned, ends at latest result if missing
      • tags - the tags to be present in the returned results (TODO: filter tags out)
      • order_by - ASCENDING or DESCENDING, order by ascending or descending time
      • page_size - the maximum number of items to return, server chooses if missing
      • page_token - the client uses this field to request a specific page of the list results (see pagination)
      • TODO: complex queries on fields, probably not MVP-scope
    • QueryResultsResponse
      • results - repeated Result
      • next_page_token - an opaque base64-encoded protobuf structure used to query the next page (see pagination)
    • POST /v1/results/query
    • Use cases:
      • The web UI client needs to display a graph
  • AddResults(AddResultsRequest) -> (AddResultsResponse)
    • AddResultsRequest
      • results - repeated Result
    • AddResultsResponse
      • results - repeated Result
    • POST /v1/results/add
    • Use cases:
      • The agent report results from Probes executions to the server

State

Fields

Name Type Description / Example
check string The relative resource name of the Check that this state resulted from
agent string The relative resource name of the Agent that this state resulted from
probe_configuration string The relative resource name of the ProbeConfiguration that this state resulted from
timestamp Timestamp The time at which the state was evaluated. The time is always localized to UTC coordinates.
type StateType The type of the state : {UNKNOWN, OK, WARNING, CRITICAL}
reason string A description of the cause of this state (can be empty)
children Object The nested children from a QueryStatesRequest’s children_mask field.
children.check Check The Check that this state resulted from
children.agent Agent The Agent that this state resulted from
children.probe_configuration ProbeConfiguration The ProbeConfiguration that this state resulted from

Methods

  • QueryStates(QueryStatesRequests) -> (QueryStatesResponse)
    • QueryStatesRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • probe_configurations - repeated ProbeConfiguration a list of ProbeConfiguration names to return current states for.
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned States, e.g. check, agent, probe_configuration. Leave empty for no nested resources.
      • page_size - the maximum number of items to return, server chooses if missing
      • page_token - the client uses this field to request a specific page of the list results (see pagination)
    • QueryStatesResponse
      • states - repeated State The states of all corresponding checks
      • next_page_token - an opaque base64-encoded protobuf structure used to query the next page (see pagination)
    • POST /v1/organizations/<parent>/states/query
    • Use cases:
      • A user wants to list states in the dashboard of the web UI

Notification

Fields

Name Type Description / Example
check string The relative resource name of the Check that this notification is about
agent string The relative resource name of the Agent that this notification is about
timestamp Timestamp The time at which the notification was issued. The time is always localized to UTC coordinates.
event EventType The type of the notification : {NOTIFIED, ACKNOWLEDGED, SNOOZED}
children Object The nested children from a QueryStatesRequest’s children_mask field.
children.check Check The Check that this state resulted from
children.agent Agent The Agent that this state resulted from

Methods

  • QueryNotifications(QueryNotificationsRequests) -> (QueryNotificationsResponse)
    • QueryNotificationsRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • probe_configurations - repeated ProbeConfiguration a list of the ProbeConfiguration to return latest notification for.
      • children_mask - a FieldMask containing the names of the related resources to nest into the returned States, e.g. check, agent, probe_configuration. Leave empty for no nested resources.
      • page_size - the maximum number of items to return, server chooses if missing
      • page_token - the client uses this field to request a specific page of the list results (see pagination)
    • QueryNotificationsResponse
      • notifications - repeated Notification The notification of all corresponding checks-agents
      • next_page_token - an opaque base64-encoded protobuf structure used to query the next page (see pagination)
    • POST /v1/organizations/<parent>/notifications/query
    • Use cases:
      • A user wants to list notifications in the pulse page of the web UI
      • A user wants to get the latest notification for a specific check-agent in the web UI
  • AddNotifications(AddNotificationRequests) -> (Notification)
    • AddNotificationsRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • probe_configuration - ProbeConfiguration to add a notification for.
      • event - the type of event to update the notification to.
    • POST /v1/organizations/<parent>/notifications/add
    • Use cases:
      • A user wants to acknowledge a notification in the pulse page of the web UI
      • A user wants to snooze a notification in the pulse page of the web UI

Tag

Fields

Name Type Description / Example
name string organizations/ODEwMzAwMjktYzQ1ZS00OT/tags/abced - the “basename” of the tag is the base64-encoded name (without padding)
display_name string The effective name of the Tag (abcde)
note string Free text field associated withe the Tag (ABCDE servers)
color string RGB color associated with the Tag (#34495e)

Methods

  • ListTags(ListTagsRequest) -> (ListTagsResponse)
    • ListTagsRequest
      • parent (mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
      • page_size: maximum number of results to be returned by the server
      • page_token: an opaque base64-encoded protobuf structure used to query the next page
    • ListTagsResponse
      • tags - repeated Tag
      • next_page_token, page_token to be used to get the next page
    • GET /v1/organizations/<parent>/tags
    • Use cases:
      • a user wants to list all the Tags of a specific Organization from the Web UI
  • CreateTag(CreateTagRequest) -> (Tag)
    • CreateTagRequest
      • parent (mandatory): the relative resource name of the parent organization
      • tag: the Tag to create, excluding name which will be generated by the server
    • POST /v1/organizations/<parent>/tags
    • Use cases:
      • a user wants to add a Tag in the Web UI
  • UpdateTag(UpdateTagRequest) -> (Tag)
    • UpdateTagRequest
      • tag (mandatory): a Tag containing the fields to update
      • update_mask : FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)
    • PUT /v1/organizations/<parent>/tags/<name>
    • Use cases:
      • a user wants to modify a Tag in the Web UI
  • DeleteTag(DeleteTagRequest) -> ()
    • DeleteTagRequest
      • name (mandatory)
    • DELETE /v1/organizations/<parent>/tags/<name>
    • Use cases:
      • a user wants to remove a Tag in the Web UI