.. meta::
    :description: This documentation will guide you through the use of the Memset API.

.. index:: cURL example, JSON, example

.. _curl-example:

cURL Example
============

The API can be used easily with `cURL <http://curl.haxx.se/>`_ 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
:func:`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
:ref:`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.