cURL Example

The API can be used easily with cURL or any other command line based HTTP client thanks to the REST interface.

The request URL is built using the following steps:

• The base URL for the API: https://api.memset.com/v1/json/.
• The method name: i.e. service.info.
• Optionally a name parameter: ie. myserver1.

According to the previous example, our request URL for the service.info() method (that requires just one name parameter) would be:

https://api.memset.com/v1/json/service.info/myserver/

The API key required to authenticate can be provided in two ways:

• Using the api_key GET parameter.
• Using basic HTTP authentication mechanism with the api_key as the username and the password is ignored.

Following our previous example (substitute API_KEY_HEX with a valid API key), the cURL invocation including the API key in a GET parameter would be:

curl 'https://api.memset.com/v1/json/service.info/myserver1/?api_key=API_KEY_HEX'

Including the API key as part of the basic HTTP authentication mechanism, the cURL invocation would be:

curl --user API_KEY_HEX:x https://api.memset.com/v1/json/service.info/myserver1/

Responses will be delivered as an HTTP document with JSON encoded data with content type application/json. An example of a valid response would be:

{
    "status": "LIVE",
    "renewal_price_currency": "GBP",
    "type": "miniserver",
    "name": "myserver1",
    "expiry_date": "2012-12-01",
    "renewal_price_amount": 21.60,
    "nickname": "www",
    "start_date": "2010-12-01",
    "renewal_price_vat": 4.34
}

Invalid responses will cause one of the HTTP status codes listed in Errors to be returned along with a JSON encoded dictionary with a bit more information in.

For example this request for a nonexistent server:

curl --user API_KEY_HEX:x https://api.memset.com/v1/json/service.info/BADSERVERNAME/

Returns this JSON dictionary with a 404 HTTP status code:

{
    "error_type": "ApiErrorDoesNotExist",
    "error_code": 3,
    "error": "Couldn't find service with name 'BADSERVERNAME'"
}

To pass more complicated parameters it is necessary to JSON encode them in the parameters argument:

curl --data-urlencode 'parameters={"name":"myserver","api_key":"API_HEX_KEY"}' https://api.memset.com/v1/json/service.info/

This supplies a JSON encoded dictionary with a name parameter and an api_key parameter. The parameters argument can be used to pass all the parameters and is the only way to pass complex data structures.