VoIP Spear: VoIP Spear API

Description

An endpoint is the computer/phone/router/etc you would like to monitor. An endpoint is really just an IP address (or hostname) that VoIP Spear can test to.

By default, endpoints are created with 'ping' testing (which uses ICMP for testing). VoIP Spear is also able to do SIP testing (via SIP OPTIONS requests) or UDP testing (using the software Sentry or hardware Probe). If you would like to do SIP or UDP testing of your endpoints, please contact VoIP Spear for more information.

Endpoint Object

Field	Description
id	An integer that uniquely identifies the endpoint.
name	Name of the endpoint.
ip_address	The IP address (or hostname) of the endpoint.
port	The port the tests should go to. For ping/ICMP testing, this port is not used.
description	Description of the endpoint.
category	'ping', 'sip', or 'udp'.
created_at	The date and time the endpoint was created.
deleted_at	The date and time the endpoint was cancelled.
server_ids	Array of server ID's for the endpoint
alert_threshold	MOS score below which the endpoint is in an outage state. If this is null, `alert_ids` must be empty.
alert_ids	Array of alert ID's for the endpoint.


{
  "id": 6,
  "ip_address": "216.18.5.21",
  "port": null,
  "name": "NYC Office",
  "description": null,
  "category": "ping",
  "created_at": "2008-01-01 07:00:00",
  "deleted_at": null,
  "server_ids": [12, 34, 56],
  "alert_threshold": 3.9,
  "alert_ids": [1, 4]
}

Commands

Action	Method	URL
List your endpoints	GET	`/endpoints`
Show info for an endpoint	GET	`/endpoints/<endpoint_id>`
Create a new endpoint	POST	`/endpoints`
Update an endpoint	PATCH	`/endpoints/<endpoint_id>`
Delete/cancel endpoint	DELETE	`/endpoints/<endpoint_id>`
Recover a deleted endpoint	PATCH	`/endpoints/<endpoint_id>/activate`

List your endpoints

Usage

GET /endpoints

Description

By default, this returns all active endpoints for your account. However, you can use the following parameters to constrain the search.

Arguments

name	Case-insensitive partial match on the name of the endpoint.
ip_address	Case-insensitive partial match on the IP address/hostname of the endpoint.
status	Status ("active", "cancelled") of the endpoints. Default: "active".

      GET /endpoints
      
{
  "collection": [
    {
      "id": 6,
      "ip_address": "21.18.57.21",
      "port": null,
      "name": "Toronto01",
      "description": "this is a test description",
      "category": "ping",
      "created_at": "2008-01-01 07:00:00",
      "deleted_at": null,
      "server_ids": [12, 34, 56],
      "alert_threshold": 3.9,
      "alert_ids": [1, 4]
    },
    {
      "id": 8,
      "ip_address": "42.177.23.176",
      "port": null,
      "name": "Julia Home",
      "description": null,
      "category": "ping",
      "created_at": "2008-01-01 07:00:00",
      "deleted_at": null,
      "server_ids": [12, 34, 56],
      "alert_threshold": null,
      "alert_ids": []
    },
    {
      "id": 23395,
      "ip_address": "1.2.3.4",
      "port": null,
      "name": "Test endpoint",
      "description": null,
      "category": "ping",
      "created_at": "2017-04-12 09:35:34",
      "deleted_at": null,
      "server_ids": [1060, 1074, 1081],
      "alert_threshold": null,
      "alert_ids": []
    }
  ],
  "metadata": {
    "count": 3
  }
}

Show info for an endpoint

Usage

GET /endpoints/<endpoint_id>

      GET /endpoints/36
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
  "server_ids": [12, 34, 56],
  "alert_threshold": 4.2,
  "alert_ids": [1, 4]
}

Create new endpoint

Usage

POST /endpoints

Description

Note that you can optionally define which servers to use for testing this endpoint using the argument server_ids[]. You can use codec, interpacket_ms, and num_tests also, however it's not recommended to provide these arguments unless you have an advanced understanding of VoIP testing and how VoIP Spear works.

For more granular control of the tests for your endpoint, refer to the VoIP Tests section

Arguments

name	The name of this endpoint.
description	A description for the endpoint.
ip_address	The IP address (or FQDN) of the endpoint.
port	The port number for the endpoint. Most endpoints leave this as null.
category	The type of endpoint ("ping", "sip", "udp"). Default: null (which is "ping").
server_ids[]	(optional) Array of Server ID's for testing this endpoint. Note that this is an array so you must pass this value as follows: `&server_id[]=1&server_id[]=2`
codec	(optional) Codec to use for the testing. Default: g711. Options: g711, g723, g729, gsm_fr, gsm_efr, ilbc, g722, speex.
interpacket_ms	(optional) Number of milliseconds between packets of each test.
num_tests	(optional) Number of individual tests/packets to use for each round of testing.
alert_threshold	(optional) The threshold below which the endpoint is in an outage state.
alert_ids[]	(optional) Array of Alert ID's for this endpoint. Note that this is an array so you must pass this value as follows: `&alert_id[]=1&alert_id[]=2`.

Note the link between alert_threshold and alert_ids. If you set alert_threshold to null, then alert_ids must be empty. If you provide a value for alert_threshold, you must also provide alert_ids.

      POST /endpoints     { "ip_address": "1.2.3.4", "name": "New endpoint", "alert_threshold": 4.0, "alert_ids[]": 4 }
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
  "server_ids": [],
  "alert_threshold": 4.0,
  "alert_ids": [4]
}

      Example with server_ids[] supplied.

      POST /endpoints     { "ip_address": "1.2.3.4", "name": "New endpoint", "server_ids[]", 1024, "server_ids[]", 2048 }
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
  "server_ids": [1024, 2048],
  "alert_threshold": null,
  "alert_ids": []
}

Update an endpoint

Arguments

PATCH /endpoints/<endpoint_id>

The fields you may specify when updating an endpoint are similar to creating a new endpoint. The only difference is that you cannot change the IP address of the endpoint after it is created.

Description

For more granular control of the tests for your endpoint, refer to the VoIP Tests section

Arguments

name	The name of the endpoint.
description	Description for the endpoint.
port	The port number for the endpoint. Most endpoints leave this as null.
category	The type of endpoint ("ping", "sip", "udp"). Default: null (which is "ping").
server_ids[]	(optional) Array of Server ID's for testing this endpoint. Note that this is an array so you must pass this value as follows: `&server_id[]=1&server_id[]=2`
codec	(optional) Codec to use for the testing. Default: g711. Options: g711, g723, g729, gsm_fr, gsm_efr, ilbc, g722, speex.
interpacket_ms	(optional) Number of milliseconds between packets of each test.
num_tests	(optional) Number of individual tests/packets to use for each round of testing.
alert_threshold	(optional) The threshold below which the endpoint in in an outage state.
alert_ids[]	(optional) Array of Alert ID's for this endpoint. Note that this is an array so you must pass this value as follows: `&alert_id[]=1&alert_id[]=2`.

      PATCH /endpoints/23400     args: {"name": "New endpoint name" }
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint name",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
  "server_ids": [1024, 2048],
  "alert_threshold": null,
  "alert_ids": []
}

Delete/cancel endpoint

Usage

DELETE /endpoints/<endpoint_id>

Description

Deletes an endpoint. Note that the endpoint can be recovered after this.

      DELETE /endpoints/234232
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": "2017-04-17 01:35:15",
  "server_ids": [1024, 2048],
  "alert_threshold": null,
  "alert_ids": []
}

Recover deleted endpoint

Usage

PATCH /endpoints/<endpoint_id>/activate

      PATCH /endpoints/234232/activate
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
  "server_ids": [1024, 2048],
  "alert_threshold": null,
  "alert_ids": []
}