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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.
¶ 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.