Developers API

Using the Wormly Developers API (WAPI) is simple. It can be a simple as fetching a URL:

In this example, we're invoking the enableHostUptimeMonitoring command, which instructs Wormly to enable monitoring of the specified host. Let's run through each part of the URL:

1. https://api.wormly.com/
   This is the endpoint for all Wormly API calls. The URL of any call you make will begin with this endpoint.
2. key = XXXXXXX
   Your API key, to authenticate the API call. Create & view your API keys.
3. response = json
   Specifies the desired response format. Permitted values are json, xml, and php.
4. cmd = enableHostUptimeMonitoring
   Specifies which API command to execute. View all Wormly API commands.
5. hostid = 123456
   All remaining parameters (in this case hostid) are passed to the API command being executed. In this instance we are specifying the ID of the Wormly host to be enabled.

Note: You can supply these parameters as an HTTP POST rather than a GET request. In fact we recommend you do this, particularly for state changing operations. Take a look at our PHP example using HTTP POST.

Wormly API Responses

Your application MUST check the HTTP Response code received in every API call. If you receive a 200 OK response, then your API call was successful - any other response indicates failure.

In addition to the HTTP response code, WAPI returns additional information in the requested response format. Here's what the HTTP response body would look like in our example:

Not a particularly exciting response; merely confirming that the operation completed without error. Note that the response is a JSON object - had we made a request for an XML or PHP response, we would see:

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <errorcode>0</errorcode>
</response>

and

respectively.

Error Handling

Take a look at this example of a WAPI request that triggers an error - note that we are supplying a non-numeric value to hostid:

Our complete HTTP response would look like:

HTTP/1.1 400 Bad Request
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <errorcode>53</errorcode>
    <errormsg>The following data types contain invalid data (type mismatch): hostid</errormsg>
</response>

Note both the 400 Bad Request HTTP response, as well as the errorcode and errormsg properties of the response object. Had we requested a JSON or PHP response format, we would see an identical response object expressed in those formats.

Limits

We are not currently enforcing any strict limits on your usage of the API, so you are free to do as you see fit. But we politely ask that you behave respectfully toward our API server and don't hit it too hard. Naturally we reserve the right to introduce limits as we see fit, and will provide you with advance notice.