The SpeedSentry PHP API¶

You can use the Inesonic, LLC SpeedSentry PHP API to more easily connect your PHP based website to SpeedSentry. The PHP API provides all the capabilities provided by our REST API.

The PHP API is containing in a single class named RestApiVI in the Inesonic namespace. The class will automatically detect if you are running the class within a WordPress installation and will use functions provided by WordPress, if available. Non-WordPress based sites will fall back on native PHP functions.

Downloading The API¶

The PHP API is maintained on github. You can find the repository at https://github.com/tuxidriver/speedsentry_php_api.

You can download a zip file containing the code by clicking on the Code button and selected Download ZIP.

`Inesonic\RestApiV1` Class Reference¶

namespace Inesonic¶

class RestApiV1¶

Class that encapsulates the Inesonic REST API.

Public Functions

Inesonic\RestApiV1::__construct(string $customer_identifier = "", string $rest_api_secret = "", int $default_time_delta = 0)

Constructor

param $customer_identifier: The identifier you should use as your identity when communicating with Inesonic infrastructure. You can obtain this setting from the Inesonic Account Settings page.
param $rest_api_secret: The secret you should use to authenticate against Inesonic infrastructure. You can obtain this setting from the Inesonic Account Settings page. Note that the value must be in raw binary format, not base-64 encoded.
param $default_time_delta: An integer value holding the last calculated time delta. The value is used to generate authorization hashes.

Inesonic\RestApiV1::setCustomerIdentifier(string $customer_identifier)

Method you can use to update your customer identifier.

param $customer_identifier: The identifier you should use as your identity when communicating with Inesonic infrastructure. You can obtain this setting from the Inesonic Account Settings page.

Inesonic\RestApiV1::customerIdentifier()

Method you can use to obtain you currently set customer identifier.

return: Returns the current customer identifier.

Inesonic\RestApiV1::setRestApiSecret(string $rest_api_secret, bool $is_base_64_encoded)

Method you can use to update your REST API secret.

param $rest_api_secret: The secret you should use to authenticate against Inesonic infrastructure. You can obtain this setting from the Inesonic Account Settings page.
param $is_base_64_encoded: If true, the provided secret is currently base-64 encoded. If false, the secret is a raw binary string.
return: Returns true if the provided secret is valid. Returns false if the provide secret’s length is invalid.

Inesonic\RestApiV1::setTimeout(string $timeout)

Method you can use to update the timeout to be used.

param $timeout: The new timeout value to be used. Value is in seconds.

Inesonic\RestApiV1::timeout()

Method you can use to obtain the current timeout value.

return: Returns the current timeout value.

Inesonic\RestApiV1::setTimeDelta(string $time_delta)

Method you can use to update the currently used time delta.

param $time_delta: The time delta between this system and remote Inesonic infrastructure.

Inesonic\RestApiV1::timeDelta()

Method you can use to obtain you currently employed time delta value.

return: Returns the current time delta value.

Inesonic\RestApiV1::setTimeDeltaCallback( $time_delta_callback)

Method you can use to specify a callback function that can be used to store off time delta values. The function will be called whenever the REST API detects a time delta error.

The callback function is defined to be usable with the WordPress update_option function. Any function you employ should be of the form:

callback(string $option, $new_value);

The option string is as specified by the TIME_DELTA_OPTION constant.

param $time_delta_callback: The time delta callback to be used. A value of null (default) disables the use of a callback function.

Inesonic\RestApiV1::timeDeltaCallback()

Method you can use to obtain you currently employed time delta callback function.

return: Returns the current time delta callback function. A value of null is returned if time delta callbacks are not enabled.

Inesonic\RestApiV1::capabilitiesGet()

Method you can use to determine your capabilities based on your current subscription.

return

Returns an associative array indicating what features you have access to. The associative array will contain the fields listed in Table 2. A null value is returned on error.

Table 2 capabilitiesGet Return Values¶
Key	Type	Holds
customer_active	bool	Boolean indicating if this customer has confirmed their email address.
maximum_number_monitors	int	Integer value indicating the maximum number of monitors this customer can setup under their subscription.
multi_region_checking	bool	Boolean indicating if the customer’s monitors are tracked across multiple geographic regions.
paused	bool	Boolean indicating true if maintenance mode is enabled and monitoring is temporarily paused.
polling_interval	int	Integer value indicating the seconds between test messages to each server.
supports_content_checking	bool	Boolean value indicating if the customer can use Inesonic’s content checking feature.
supports_keyword_checking	bool	Boolean value indicating if the customer can use Inesonic’s keyword checking feature.
supports_latency_tracking	bool	Boolean value indicating if site reponse times are measured and recorded.
supports_maintenance_mode	bool	Boolean value indicating if the customer can use maintenance mode.
supports_ping_based_polling	bool	Boolean value indicating if echo ICMP frames will be sent to the server to improve or ability to detect when a site goes down.
supports_post_method	bool	Boolean value indicating if the customer can use all supported HTTP methods/verbs to validate forms and REST APIs.
supports_rest_api	bool	Boolean value indicating if the customer can use the full capabilities of the Inesonic REST API.
supports_ssl_expiration_checking	bool	Boolean value indicating if SSL expiration checking will be performed.
supports_wordpress	bool	Boolean value indicating if the customer can use the limited WordPress REST api features.

Inesonic\RestApiV1::hostsGet(int $host_scheme_id)

Method you can use to obtain information about a specific host or authority.

return

Returns an associative array holding information about this host. The associative array will contains the members listed in Table 3. A null value is returned on error.

Table 3 hostsGet Return Values¶
Key	Type	Holds
host_scheme_id	int	The internal ID used to reference this host.
ssl_expiration_timestamp	int	The Unix timestamp indicating when the SSL certificate for this host is going to expire. A value of 0 is provided if there is no certificate or the data has not yet been read.
url	str	The authority for this host.

param $host_scheme_id

The ID of the host to obtain information for.

Inesonic\RestApiV1::hostsList()

Method you can use to obtain a list of hosts/authorities for the current customer.

return: Returns an associative array indexed by host/scheme ID. Each array entry is also an associative array holding values documented in Table 3. A null value is returned on error.

Inesonic\RestApiV1::monitorsGet(int $monitor_id)

Method you can use to obtain information about a specific monitor.

return

Returns an associative array indexed by host/scheme ID. Each array entry is an associative array holding the key/value pairs listed in Table 4. A null value is returned on error.

Table 4 monitorsGet Return Values¶
Key	Type	Holds
monitor_id	int	The ID of the requested monitor.
host_scheme_id	int	The host/scheme ID of the server associated with this monitor.
path	str	The path under the host/scheme to this monitor.
user_ordering	int	An integer value starting from 0 indicating the position of this monitor in the Inesonic Account Settings page.
method	str	A string holding the HTTP method or verb used to access the page or endpoint. supported values are: `get` `head` `post` `put` `delete` `options` `patch`
content_check_mode	str	A string holding the desired content check mode. Supported values are: `no_check` `content_match` `all_keywords` `any_keywords`
keywords	array	An array holding the keywords to check for. Each keyword will be base-64 encoded as per RFC 4648.
user_agent	str	Value used with POST, PUT, PATCH, and DELETE. Indicates the User-Agent string to report in the request header.
content_type	str	Value used only with POST, PUT, PATCH, and DELETE. Value indicates the Content-Type to report in the request header. Supported values are listed in Table 5
post_content	str	Value used only with POST, PUT, PATCH, and DELETE. Value contains the content sent in the request body. The supplied data is base-64 encoded as per RFC 4648.

Table 5 PHP Content-Type Values¶
Value	Header Content-Type Value
`text`	text/plain
`json`	application/json
`xml`	application/xml

param $monitor_id

The ID of the monitor to retrieve information for.

Inesonic\RestApiV1::monitorsList(string $order_by = 'monitor_id')

Method you can use to obtain a list of monitors.

param $order_by

A value indicating the desired format of the return data. Accepted values are listed in Table 6.

Table 6 PHP Monitor List $order_by Values¶
Value	Returned Ordering
`monitor_id`	The returned list will be indexed by The internal monitor ID.
`user_ordering`	The returned list will be indexed by the user ordering in the Account settings page. The first entry will be “0”.
`url`	The returned list will be indexed by the full URL of the monitor.

return

Returns an associative array indexed by either the monitor ID, the user ordering, or URL. Each array entry is an associative holding the values listed in Table 7.

Table 7 monitorsList Return Values¶
Key	Type	Holds
monitor_id	int	The ID of the requested monitor.
host_scheme_id	int	The host/scheme ID of the server associated with this monitor.
path	str	The path under the host/scheme to this monitor.
url	str	The full URL used to access the monitor.
user_ordering	int	An integer value starting from 0 indicating the position of this monitor in the Inesonic Account Settings page.
method	str	A string holding the HTTP method or verb used to access the page or endpoint. supported values are: `get` `head` `post` `put` `delete` `options` `patch`
content_check_mode	str	A string holding the desired content check mode. Supported values are: `no_check` `content_match` `all_keywords` `any_keywords`
keywords	array	An array holding the keywords to check for. Each keyword will be base-64 encoded as per RFC 4648.
user_agent	str	Value used with POST, PUT, PATCH, and DELETE. Indicates the User-Agent string to report in the request header.
content_type	str	Value used only with POST, PUT, PATCH, and DELETE. Value indicates the Content-Type to report in the request header. Supported values are listed in Table 5
post_content	str	Value used only with POST, PUT, PATCH, and DELETE. DELETE. Value contains the content sent in the request body. The supplied data is base-64 encoded as per RFC 4648.

Inesonic\RestApiV1::monitorsUpdate(array $monitor_data)

Method you can use to update the customer’s monitor settings.

param $monitor_data

An associative array indexed by a zero based user ordering value. Each array entry should be an associative array containing the parameters listed in Table 8. Note that most parameters have default values and are optional.

Table 8 monitorsUpdate Parameter Values¶
Key	Type	Default	Function
uri	str	-required-	Either a full URL with a host and scheme or a path indicating the location to be monitored. If just a path is provided then the host/scheme from the previous monitor, based on user ordering, will be used.
method	str	‘get’	The HTTP method used to access the endpoint. Specify one of: `get` `head` `post` `put` `delete` `options` `patch` If not specified, then ‘get’ is assumed.
content_check_mode	str	‘no_check’	The desired content check mode. Supported values are: `no_check` `content_match` `all_keywords` `any_keywords` If not specified, then ‘no_check’ is assumed.
keywords	array	array()	A list of keywords to check for. Each keyword should be base-64 encoded as per RFC 4648.
post_content_type	str	‘text’	The post content type to provide in the POST header. Supported values are listed in Table 5. If not specified, then ‘text’ is assumed.
post_user_agent	str	‘’	The user agent to report in the post header. If not specified or an empty string, then an default User-Agent string will be reported.
post_content	str	‘’	The post content to be sent. Value should be base-64 encoded as per RFC 4648.

return

Return an empty array on success. On error, this method returns an array of error where each entry includes a user ordering value and an error message. A null value is returned if a communications error occurred.

Inesonic\RestApiV1::regionsGet(int $region_id)

Method you can use to obtain a textual description of a geographic region where latency measurements were taken.

param $region_id: The ID of the region to obtain a textual description for.
return: Returns a textual description of the requested region. A null value is returned on error.

Inesonic\RestApiV1::regionsList()

Method you can use to obtain an array of regions indexed by region ID.

return: Returns an array of regions indexed by region ID. Each entry is an array containing a ‘region_id’ entry and ‘description’ entry. A null value is returned on error.

Inesonic\RestApiV1::eventsGet(int $event_id)

Method you can use to obtain event data by event ID.

return

Returns an array providing information on the event. The array will contain the members listed in Table 9.

Table 9 eventsGet Return Values¶
Key	Type	Function
event_id	int	The ID used to identify this event.
message	str	The type of event that occurred. Value will be one of: `no_response` `working` `content_changed` `keywords` `ssl_certificate_expiring` `ssl_certificate_renewed` `custom_1` `custom_2` `custom_3` `custom_4` `custom_5` `custom_6` `custom_7` `custom_8` `custom_9` `custom_10`
monitor_id	int	The monitor ID of the monitor that triggered the event.
timestamp	int	The Unix timestamp indicating when the event occurred.

param $event_id

The ID of the event to obtain information on.

Inesonic\RestApiV1::eventsList(int $start_timestamp = 0, int $end_timestamp = 0)

Method you can use to obtain a list of events.

return

Returns an array of events in time order with each entry containing the values listed in :numref: Table 10.

Table 10 eventsList Return Values¶
Key	Type	Function
event_id	int	The ID used to identify this event.
message	str	The type of event that occurred. Value will be one of: `no_response` `working` `content_changed` `keywords` `ssl_certificate_expiring` `ssl_certificate_renewed` `custom_1` `custom_2` `custom_3` `custom_4` `custom_5` `custom_6` `custom_7` `custom_8` `custom_9` `custom_10`
monitor_id	int	The monitor ID of the monitor that triggered the event.
timestamp	int	The Unix timestamp indicating when the event occurred.

param $start_timestamp

The starting timestamp for the events to be returned. Value is inclusive. A value of zero means no start time.

param $end_timestamp

The ending timestmap for the events to be returned. Value is inclusive. A value of 0 means “now”.

Inesonic\RestApiV1::eventsCreate(int $event_type, str $message, int $monitor_id = 0)

Method you can use to create a new customer event.

param $event_type: An integer value between 1 and 10 indicating the desired custom event type.
param $message: The message to be sent.
param $monitor_id: The ID of the monitor to tie to this event. A value of 0 (default) will cause the event to be tied to the first monitor.
return: Returns true on success. Returns false on error.

Inesonic\RestApiV1::statusGet(int $monitor_id)

Method you can use to obtain the last reported status of a monitor.

param $monitor_id: The ID of the monitor being queried.
return: Returns one of ‘failed’, ‘working’, ‘unknown’. An unknown status indicates either the endpoint has never been tested or no data has been reported yet. A null value is returned on error.

Inesonic\RestApiV1::statusList()

Method you can use to obtain the last reported status of all monitors.

return: Returns an array indexed by monitor ID. Each entry will contain one of ‘failed’, ‘working’, or ‘unknown’. An unknown status indicates either the endpoint has never been tested or no data has been reported yet. A null value is returned on error.

Inesonic\RestApiV1::multipleList()

Method you can use to obtain the multiple sets of values simultaneously. The function exists specifically to support WordPress.

return

Returns an array containing the entries listed in Table 11.

Table 11 multipleList Return Values¶
Key	Contains
monitors	A list of monitors by user order. Each entry will be a dictionary containing the key-value pairs documented in Table 7.
authorities	A list of host/scheme entries indexed by host_scheme_id. Each entry will be a dictionary containing the key-value pairs documented in Table 3.
events	A list of events in time order. Each entry will be a dictionary containing the key-value pairs documented in Table 9.
status	A dictionary of status values by monitor ID. Each entry will contain one of `unknown` `working` `failed`

Inesonic\RestApiV1::latencyList(int $monitor_id = 0, int $region_id = 0, int $start_timestamp = 0, int $end_timestamp = 0)

Method you can use to obtain latency data. Be aware that this method can return a very large amount of data.

return

Returns an array containing two entries as listed in Table 12.

Table 12 latencyList Return Values¶
Key	Contains
latency	A list of recent raw latency values. Values will be over roughly the last 30 days. Each entry will be a dictionary of key-value pairs as documented in Table 13.
aggregated	A list of aggregated latency values. Values will represent collections of older latency data taken more than roughly 30 days ago. Each entry will be a dictionary of key-value pairs as documented in Table 14.

Table 13 Raw Latency Return Values¶
Key	Type	Contains
timestamp	int	The Unix timestamp when this value was collected.
monitor_id	int	The monitor ID of the monitor measured for this value.
region_id	int	The region ID of the region where the measurement was taken from.
latency	float	The raw latency value, in seconds.

Table 14 Aggregated Latency Return Values¶
Key	Type	Contains
monitor_id	int	The monitor ID of the monitor measured for this value.
region_id	int	The region ID of the region where this measurement was taken.
timestamp	int	A timestamp associated with a randomly selected value within the aggregation set.
latency	float	A randomly selected latency value within the aggregation set. Value is in seconds.
start_timestamp	int	The timestamp of the first latency value used to create this aggregation set.
end_timestamp	int	The timestamp of the last latency value used to create this aggregation.
average	float	The average value of the raw latency values used to create this aggregation. Value is in seconds.
variance	float	The population variance of the raw latency values used to create this aggregation. Value is in seconds-squared.
minimum	float	The mimumum raw latency value found when creating this aggregation. Value is in seconds.
maximum	float	The maximum raw latency value found when creating this aggregation. Value is in seconds.
number_samples	int	The number of raw latency measurements that were used to create this aggregation set.

param $monitor_id

The monitor to retrieve data over. A value of 0 indicates all monitors.

param $region_id

The region to retrieve data over. A value of 0 indicates all regions.

param $start_timestamp

The starting timestamp to retrieve data over. A value of 0 indicates no start timestamp.

param $end_timestamp

The ending timestamp to retrieve data over. A value of 0 indicates no end timestamp.

Inesonic\RestApiV1::latencyPlot(array $settings)

Method you can use to obtain a plot of latency data.

param $settings

The plot settings array. This value supports a large number of possible fields listed in Table 15. Note that most parameters are optional. Reasonable default values will be used for omitted parameters.

Table 15 latencyPlot Parameters¶
Key	Type	Default Value	Function
plot_type	str	‘history’	Indicates the desired type of plot. Supported values are ‘history’ and ‘histogram’.
host_scheme_id	int	-all-	Indicates the plot should be limited to monitors on this server. This value is mutually exclusive with ‘monitor_id’.
monitor_id	int	-all-	Indicates the plot should be limited to this monitor. This value is mutually exclusive with ‘host_scheme_id’.
region_id	int	-all-	Indicates the plot should be limited to one or more monitors in one region.
start_timestamp	int	0	Indicates the plot should exclude values before this time.
end_timestamp	int	-now-	Indicates the plot should exclude values after this time.
title	str	‘Latency Over Time’	A UTF-8 encoded title to include in the plot.
x_axis_label	str	‘Date/Time’	The UTF-8 encoded text for the X axis label.
y_axis_label	str	‘Latency (seconds)’	The UTF-8 encoded text for the Y axis label.
date_format	str	‘MMM dd yyy - hh:mm’	The date format to apply to date/time fields. For details, see Date Format Codes.
title_font	str	-dafault-	The title font to be used. For details, see Font Encoding.
axis_title_font	str	-default-	The font to use for axis title text. For details, see Font Encoding.
axis_label_font	str	-default-	The font to use for axis labels. For details, see Font Encoding.
minimum_latency	float	0	The minimum latency value to show. Value is in seconds.
maximum_latency	float	auto-scale	The maximum latency value to show. Value is in seconds.
log_scale	bool	false	A boolean value indicating if log scale should be used for the Y axis. Only works for history plots.
width	int	1024	The plot width, in pixels.
height	int	768	The plot height, in pixels.
format	str	‘PNG’	The returned data format, supported values are ‘PNG’, and ‘JPG’.

return

Returns an array holding the values listed in Table 16. A null value will be returned if a communication error occurs.

Table 16 latencyPlot Return Values¶
Key	Type	Contains
content_type	str	The returned content type. On success, ‘image/png’ or ‘image/jpg’ is returned. On failure, ‘application/json’ is returned.
body	str	The returned payload. On success, this will contain raw byte data holding the image. On failure, the body will contain a JSON encoded response explaining the failure.

Inesonic\RestApiV1::customerPause(bool $pause)

Method you can use to enter or exit maintenance mode.

param $pause: If true, then all monitoring of your infrastructure will stop and SpeedSentry will enter maintenance mode. If false, monitoring will resume and SpeedSentry will exit maintenance mode.
return: Returns true on success. Returns false on error.

Public Members

const INESONIC_AUTHORITY = "https://rest.1.speed-sentry.com": The authority containing the customer REST APIs.

const REST_API_SECRET_LENGTH = 56: The required length of the final REST API secret, in bytes.

const DEFAULT_TIMEOUT = 20: Timeout to apply to all requests, in seconds.

const HASH_ALGORITHM = 'sha256': The hash algorithm.

const TIME_DELTA_OPTION = 'inesonic_rest_time_delta': The name of the option used to store off the time delta.

const TIME_DELTA_ROUTE = '/td/': Route to the time delta slug.

const CAPABILITIES_GET_ROUTE = '/v1/capabilities/get': Route for the capabilities/get function.

const HOSTS_GET_ROUTE = '/v1/hosts/get': Route for the hosts/get function.

const HOSTS_LIST_ROUTE = '/v1/hosts/list': Route for the hosts/list function.

const MONITORS_GET_ROUTE = '/v1/monitors/get': Route for the monitors/get function.

const MONITORS_LIST_ROUTE = '/v1/monitors/list': Route for the monitors/list function.

const MONITORS_UPDATE_ROUTE = '/v1/monitors/update': Route for the monitors/update function.

const REGIONS_GET_ROUTE = '/v1/regions/get': Route for the regions/get function.

const REGIONS_LIST_ROUTE = '/v1/regions/list': Route for the rgions/list function.

const EVENTS_GET_ROUTE = '/v1/events/get': Route for the events/get function.

const EVENTS_LIST_ROUTE = '/v1/events/list': Route for the events/list function.

const EVENTS_CREATE_ROUTE = '/v1/events/create': Route for the events/create function.

const STATUS_GET_ROUTE = '/v1/status/get': Route for the status/get function.

const STATUS_LIST_ROUTE = '/v1/status/list': Route for the status/list function.

const MULTIPLE_LIST_ROUTE = '/v1/multiple/list': Route for the multiple/list function.

const LATENCY_LIST_ROUTE = '/v1/latency/list': Route for the latency/list function.

const LATENCY_PLOT_ROUTE = '/v1/latency/plot': Route for the latency plot function.

const CUSTOMER_PAUSE_ROUTE = '/v1/customer/pause': Route for the customer/pause function.

Private Functions

Inesonic\RestApiV1::postMessage(array $message, string $route)

Method that posts a message and waits for a response.

param $message: The message to be sent.
param $route: The route to send the message to.
return: Returns an array holding the response body. A value of null is returned on error.

Inesonic\RestApiV1::postBinaryMessage(array $message, string $route)

Method that posts a message and waits for a response in a binary format.

param $message: The message to be sent.
param $route: The route to send the message to.
return: Returns an array holding the response body. A value of null is returned on error.

Inesonic\RestApiV1::__postMessage(array $message, string $route)

Method that posts a message and waits for a response. This function does no retries and does not adjust the time delta on an UNAUTHORIZED (401) error.

param $message: The message to be sent.
param $route: The route to send the message to.
return: Returns an array holding the status code followed by the response body. A status code of 0 is returned if the message could not be sent.

Inesonic\RestApiV1::__updateTimeDelta()

Method that determines the current time delta between the client and Inesonic infrastructure.

return: Returns true on success. Returns false on error.

The SpeedSentry PHP API¶

Downloading The API¶

Inesonic\RestApiV1 Class Reference¶

`Inesonic\RestApiV1` Class Reference¶