API usage guide

The Server Density API allows you to get access to all the monitoring data stored by the service. It also includes functions to manipulate the service such as by pausing/resuming alerts. The API is provided over standard HTTP (or HTTPS) and returns JSON which means it can be used within any programming language and on any platform.

Access to the API is provided to all accounts, free of charge.

Authentication

Each request to the API requires authentication; each request is isolated and there is no persistent session. Authentication is provided by using the username and password of a user in your Server Density account. By default, API access is disabled and must be enabled by an admin user.

For security, we recommend that you create a separate user for your API access so that if the credentials are compromised, it is easy to revoke access without risking losing your primary login details.

Enabling API access

1. Log into your Server Density account as an admin user.
2. Click the Users tab.
3. Click Edit next to the user you wish to enable API access for.
4. Tick the API enabled? box and click Edit.
5. This user now has access to the API using their username and password.

Basic usage

Endpoint

The API is accessed from a single URL for all accounts:

http://api.serverdensity.com

If you wish to use SSL encryption then you can also use HTTPS:

https://api.serverdensity.com

Versioning

To ensure future modifications to the API do not affect older applications, the API is versioned. You must append the version number to the endpoint URL. For example, accessing v1.0 of the API is done at:

http://api.serverdensity.com/1.0/

See the release notes for details of newer versions and changes to the API.

Authentication

As noted above, every request requires authentication. This is achieved by using basic access authentication. The credentials can be provided through the URL or by using the basic authentication functionality of your HTTP library. If you access the API through your web browser, it will prompt for your login details. Since the credentials are transmitted in plain text, we recommend you always use SSL by using HTTPS.

For example:

https://username:password@api.serverdensity.com/1.0/

Permissions

All API functions adhere to user group permissions as set for the user that is being used for authentication. This means a user will only be able to access data via the API for the server groups allowed by the permissions set in the web interface.

Account

In order to tell the API which access to access, you need to provide an account parameter which is the full Server Density account URL e.g. boxedice.serverdensity.com.

Functions

Each API request also requires a function command to tell the API what you want to do. This is passed as a parameter as part of the request:

c=command

See the function list for details about each command.

Other parameters

Any other parameters are passed as regular GET variables within the URL as part of the request. However, for security reasons, functions that cause changes to data in your account require their parameters to be by POST instead of GET. This is indicated in the function list where appropriate.

Example

This request returns the details for server ID 1. It can be accessed directly via a web browser or as part of a script.

https://username:password@api.serverdensity.com/1.0/?account=boxedice.serverdensity.com&c=servers/getbyid&serverId=1

Response

The response returned by the API will always be JSON. Any errors generated by the API will also be returned as JSON which means that if you ever receive a blank response or bad JSON, an error has occurred in the request itself. Every request will return a JSON response with 2 elements:

Success response

• status - 1
• data - a multi-dimensional array that will contain the data you requested.

For example the response to the above request for the details of server ID 1 would return:

{"status":1,"data":{"server":{"serverId":"1","name":"lyra.boxedice.net","ip":"67.23.6.201","location":"DFW, USA","provider":"Slicehost","notes":""}}}

Represented programmatically by PHP, this looks like:

stdClass Object
(
    [status] => 1
    [data] => stdClass Object
        (
            [server] => stdClass Object
                (
                    [serverId] => 1
                    [name] => lyra.boxedice.net
                    [ip] => 67.23.6.201
                    [location] => DFW, USA
                    [provider] => Slicehost
                    [notes] => 
                )

        )

)

Error response

• status - 2
• error
  • code - the error code for the error.
  • message - a brief description of the error.

For example, specifying an incorrect account would return:

{"status":2,"error":{"code":101,"message":"Invalid account."}}

Represented programmatically by PHP, this looks like:

stdClass Object
(
    [status] => 2
    [error] => stdClass Object
        (
            [code] => 101
            [message] => Invalid account.
        )

)