Commands
| Action | URL | Method |
|---|---|---|
| List the VoIP tests for an endpoint | /users/{user_id}/endpoints/{endpoint_id}/voip_tests | GET |
| Show info for a VoIP test | /users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id} | GET |
| Create a new VoIP test for an endpoint | /users/{user_id}/endpoints/{endpoint_id}/voip_tests | POST |
| Update a VoIP test | /users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id} | PUT |
| Delete/cancel a VoIP test | /users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id} | DELETE |
| Re-activate a cancelled/deleted VoIP test | /users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id}/activate | DELETE |
VoIP Test Fields
- id
- An integer that uniquely identifies the VoIP test.
- endpoint-id
- The ID of the endpoint this VoIP test belongs to.
- server-id
- The ID of the server doing the testing.
- mos
- The current MOS value for this VoIP test. Use the "updated-at" field to see how recent this value is.
- codec
- The codec being used for the VoIP test.
- alert-threshold
- A number between 1 and 5 indicating the point at which VoIP Spear should send out alerts for this VoIP test. Alerts are sent out when the MOS results for this VoIP test are below the alert threshold for a certain amount of time. The amount of time is defined by how the alerts are set up. To get this information, log into your account on the web site.
- alerting-since
- If the VoIP test is alerting (meaning that the MOS is below the "alert-threshold" value for a particular amount of time), this will show you the time at which it first dropped below the threshold. If this value is nil, the VoIP test is not alerting.
- created-at
- The date and time the VoIP test was created.
- deleted-at
- The date and time the VoIP test was cancelled. If this is nil, then the VoIP test has not been deleted/cancelled yet.
- updated-at
- The date and time the VoIP test was last updated.
List the VoIP tests for an endpoint
GET http://voipspear.com/users/{user_id}/endpoints/{endpoint_id}/voip_tests
In contrast to a listing of users and endpoints, a listing of VoIP tests includes both active and deleted/cancelled VoIP tests.
Example
Show info for a VoIP test
GET http://voipspear.com/users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id}
Example
Create a new VoIP test for an endpoint
POST http://voipspear.com/users/{user_id}/endpoints/{endpoint_id}/voip_tests %>
Response Code: "201 Created" or "200 OK"
When you create a new VoIP test, VoIP Spear looks to see if there's an deleted/cancelled VoIP test between this server and endpoint. If there it, then it just re-activates that VoIP test instead of creating a new one. The reason we do this is because the historical test results are preserved this way.
If a new VoIP test is created, the response code will be "201 Created" rather than the usual "200 OK". Also note that the response headers will also include the location/URL of the newly created VoIP test in this case. If an old VoIP test is re-activated as a result of this request, the response code will be "200 OK".
Here are the fields you can specify when creating a VoIP test.
- server_id
- Identifies the server that will be doing the testing for this VoIP test.
- alert_threshold
- This is a number between 1 and 5 indicating the point at which VoIP Spear should send out alerts for this VoIP test. Alerts are sent out when the MOS results for this VoIP test are below the alert threshold for a certain amount of time. The amount of time is defined by how the alerts are set up. To get this information, log into your account on the web site.
- codec
- The codec that VoIP Spear will use for this VoIP test. This must be one of 'g711', 'g729', or 'g723'.
Update a VoIP test
PUT http://voipspear.com/users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id}
The fields you may specify when updating a VoIP test are similar to creating a new VoIP test. The only difference is that you cannot change the server of the VoIP test.
- alert_threshold
- This is a number between 1 and 5 indicating the point at which VoIP Spear should send out alerts for this VoIP test. Alerts are sent out when the MOS results for this VoIP test are below the alert threshold for a certain amount of time. The amount of time is defined by how the alerts are set up. To get this information, log into your account on the web site.
- codec
- The codec that VoIP Spear should use for this VoIP test. This must be one of 'g711', 'g729', or 'g723'.
Example
Delete a VoIP test
DELETE http://voipspear.com/users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id}
Deleting a VoIP test does not remove it from the system entirely. Instead, it goes into an inactive state. We prefer to think of these VoIP tests as "cancelled" rather than "deleted." After a VoIP test has been cancelled, you can re-activate it at any time.
The servers do not run cancelled VoIP tests.
Example
Re-activate a cancelled VoIP test
PUT http://voipspear.com/users/{user_id}/endpoints/{endpoint_id}/voip_tests/{voip_test_id}/activate
Example