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

Introduction
============

[**This API and its documentation are in beta and subject to change before final release**]

Here is the API for `Memset`_ systems.

.. _Memset: https://www.memset.com/

This documentation can be accessed in a number of ways:

  * `HTML`_ (split into multiple pages, hosted on our website.)
  * `PDF`_ (downloadable.)

.. _HTML: https://www.memset.com/apidocs/
.. _PDF: https://www.memset.com/apidocs/MemsetAPI.pdf

Some parts of this documentation are generated dynamically and may change over
time. The online version is therefore recommended.

This document was generated |today|.

Types
-----

There is a single API specification that is implemented in several interfaces.
This section describes a set of types and their mapping to the different
interfaces.

This API specification uses the following data types which you will see in the documentation:

  * String
  * List
  * Dictionary
  * Boolean
  * Float
  * Integer
  * Date

The API types are mapped to the following implementation types:

+------------+------------------+---------------+----------------+
| API Spec   | XML-RPC          | JSON          | HTTP GET/POST  |
+============+==================+===============+================+
| String     | string           | String        | String         |
+------------+------------------+---------------+----------------+
| List       | array            | Array         | N/A            |
+------------+------------------+---------------+----------------+
| Dictionary | struct           | Object        | N/A            |
+------------+------------------+---------------+----------------+
| Boolean    | boolean          | true or false | String         |
+------------+------------------+---------------+----------------+
| Float      | double           | Number        | String         |
+------------+------------------+---------------+----------------+
| Integer    | int              | Number        | String         |
+------------+------------------+---------------+----------------+
| Date       | dateTime.iso8601 | String        | String         |
+------------+------------------+---------------+----------------+

Authentication
--------------

Authentication for all methods supports standard HTTP basic
authorisation over HTTPS (using the HTTP_AUTHORIZATION header).

Your api_key (32 digit hex string) should be provided as the username
and the password can be anything.

You can also pass your api_key in as an extra POST or GET parameter
named ``api_key`` when using GET or POST over HTTPS.

Access methods
--------------

JSON over HTTPS
^^^^^^^^^^^^^^^

GET or POST to this URL.  Replace METHOD_NAME with the name of the
method from the documentation, e.g. "server.info"::

    https://api.memset.com/v1/json/METHOD_NAME

You may also supply the "name" parameter as another part of the URL::

    https://api.memset.com/v1/json/METHOD_NAME/SERVICE_NAME

e.g.::

    https://api.memset.com/v1/json/server.info/myserver1

The authentication may be provided as basic authentication, or as an
api_key parameter.  See the :ref:`curl-example` for more information and
examples.

Parameters may be passed in as GET or POST parameters encoded as
strings.  Booleans are "0" or "1" and dates are in ISO 8601 format
"YYYY-MM-DD HH:MM:SS".  It isn't possible to pass List or Dictionary
types so those API methods won't work without using JSON encoding.

To pass more complicated parameters use the ``parameters`` parameter.
Its contents should be a JSON encoded dictionary which contains the
parameters to the API call.  See the :ref:`curl-example` for a walk
through.

Errors are returned as HTTP status codes with a JSON encoded return.
For example, this was returned with a ``404`` HTTP status code::

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

See :ref:`errors` for the mapping between HTTP status codes and the
various errors returned.

XML-RPC
^^^^^^^

Post your XMLRPC to this URL using the api_key as the username with BASIC authentication and any value as the password::

  https://api.memset.com/v1/xmlrpc

Some XMLRPC clients like to have the authentication in the URI, in which case write it like this::

  https://32_hex_digit_api_key:x@api.memset.com/v1/xmlrpc

See the examples for a comprehensive selection of XMLRPC in many different languages.

See :ref:`errors` for the mapping to XMLRPC error codes.

.. _json-rpc:

JSON-RPC
^^^^^^^^

The API also supports `JSON-RPC v 2.0`_

Post your JSON-RPC to this URL using the api_key as the username with BASIC authentication and any value as the password::

  https://api.memset.com/v1/jsonrpc

Some JSON-RPC clients like to have the authentication in the URI, in which case write it like this::

  https://32_hex_digit_api_key:x@api.memset.com/v1/jsonrpc

The Server only supports named parameters - not argument lists. Batch mode is supported, but only up to 100 items in the batch.

See the `implementations page`_ for libraries to use JSON-RPC and see the :ref:`python-jsonrpc-example` example for some code.

See :ref:`errors` for the mapping to JSON-RPC error codes.

.. _JSON-RPC v 2.0: http://www.jsonrpc.org/specification
.. _implementations page: http://en.wikipedia.org/wiki/JSON-RPC#Implementations