Memset API Shell

The Memset API interactive shell (ma-shell for short) is a full featured XMLRPC client that enables remote command invocation from a text terminal.

It can run a single command or an interactive session, supports JSON and XML output as well as output redirection into a file.

ma-shell Invocation

ma-shell can be invoked with the -h flag to get an online help screen:

Usage: ma-shell [options] [command [param_name param_value ...]]

Memset API interactive shell

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -u URL, --url=URL     API URL (default:
                                                https://%s:@api.memset.com/v1/xmlrpc)
  -k KEY, --api-key=KEY
                                                API KEY (required)
  -x, --xml             Use XML as output format (default: JSON)

The only required parameter is -k KEY to provide a valid API key. In all the following examples API_KEY_HEX is used instead of a real API key.

If no command is provided, ma-shell will enter the interactive mode advertising the version number and displaying a command prompt that shows the tail of the used key:

(Memset API shell v0.2)
[...a32a1fe9]>

The interactive session can be closed with the quit command or with ^D (end of file).

If a command is provided, ma-shell executes it and writes the result to standard output before exiting:

$ ./ma-shell.py -k API_KEY_HEX help system.listMethods
List all the public methods

The output can be redirected to a file using standard shell redirection.

The method invocation will use JSON by default as the output format for structured responses. XML output can be obtained using -x flag:

./ma-shell.py -k API_KEY_HEX -x service.info name myserver1
<result>
  <status>LIVE</status>
  <renewal_price_currency>GBP</renewal_price_currency>
  <type>miniserver</type>
  <name>myserver1</name>
  <expiry_date>20110917T00:00:00</expiry_date>
  <renewal_price_amount>21.60</renewal_price_amount>
  <nickname>www</nickname>
  <start_date>20110617T00:00:00</start_date>
  <renewal_price_vat>4.34</renewal_price_vat>
</result>

Note that when an interactive session has been started, the output format can’t be changed.

Command Invocation

There are two local commands:

• quit: exit the interactive session.
• help [command]: used to describe commands.

The help command without argument will display a general help screen. Use help remote to get the list of remote commands.

The remote command list is retrieved from the API service at session start.

When help is used with a remote command, the information is obtained directly from the API service.

Remote Command Invocation

Remote commands without parameters can be executed as-is using the command name, for example:

[...a32a1fe9]> service.list
(service.list result)
[
  {
        "status": "LIVE",
        "renewal_price_currency": "GBP",
        "type": "cloudstorage",
        "name": "mystorage1",
        "expiry_date": "20111112T00:00:00",
        "renewal_price_amount": 24.0,
        "nickname": "",
        "start_date": "20110617T00:00:00",
        "renewal_price_vat": 4.0
  },
  {
        "status": "LIVE",
        "renewal_price_currency": "GBP",
        "type": "miniserver",
        "name": "myserver1",
        "expiry_date": "20110917T00:00:00",
        "renewal_price_amount": 21.60,
        "nickname": "www",
        "start_date": "20110617T00:00:00",
        "renewal_price_vat": 4.34
  }
]

In the case of remote commands that require parameters, the parameters must be provided in name/value pairs. The number and name of the parameters depends on the remote command and is specified on its documentation.

For example, service.info() requires a single parameter named name. Its invocation is as follows:

./ma-shell.py -k API_KEY_HEX service.info name myserver1
{
  "status": "LIVE",
  "renewal_price_currency": "GBP",
  "type": "miniserver",
  "name": "myserver1",
  "expiry_date": "20110917T00:00:00",
  "renewal_price_amount": 21.60,
  "nickname": "www",
  "start_date": "20110617T00:00:00",
  "renewal_price_vat": 4.34
}

With commands that require more than one parameter, the order is not important as long as the name/value pairs are correct.

For example, service.set_nickname() requires two different parameters:

[...a32a1fe9]> service.set_nickname name myserver1 nickname webserver
(service.set_nickname result)
{
  "nickname": "webserver"
}

The result would be the same if the nickname parameter were first.

By default all parameter values are treated as strings, and a (type) prefix can be used to indicate the type of a specific value. The following types are supported:

• (string): a string value (default).
• (int): an integer value.
• (float): a decimal number value.
• (boolean): a boolean value (True or False, 1 or 0).
• (list): a comma separated list of strings.

For example, using a list in the type parameter of service.list():

[...a32a1fe9]> service.list type (list) cloudstorage,miniserver
(service.list result)
[
  {
        "status": "LIVE",
        "renewal_price_currency": "GBP",
        "type": "miniserver",
        "name": "myserver1",
        "expiry_date": "20110917T00:00:00",
        "renewal_price_amount": 21.60,
        "nickname": "www",
        "start_date": "20110617T00:00:00",
        "renewal_price_vat": 4.34
  },
  {
        "status": "LIVE",
        "renewal_price_currency": "GBP",
        "type": "cloudstorage",
        "name": "mystorage1",
        "expiry_date": "20111112T00:00:00",
        "renewal_price_amount": 24.0,
        "nickname": "",
        "start_date": "20110617T00:00:00",
        "renewal_price_vat": 4.0
  }
]

The output of any specific remote command invocation can be stored in a file using the pipe (¦) operator followed by the desired file name:

[...a32a1fe9]> service.list | out.json
(service.list result)
[
  {
        "status": "LIVE",
        "renewal_price_currency": "GBP",
        "type": "cloudstorage",
        "name": "mystorage1",
        "expiry_date": "20111112T00:00:00",
        "renewal_price_amount": 24.0,
        "nickname": "",
        "start_date": "20110617T00:00:00",
        "renewal_price_vat": 4.0
  },
  {
        "status": "LIVE",
        "renewal_price_currency": "GBP",
        "type": "miniserver",
        "name": "myserver1",
        "expiry_date": "20110917T00:00:00",
        "renewal_price_amount": 21.60,
        "nickname": "www",
        "start_date": "20110617T00:00:00",
        "renewal_price_vat": 4.34
  }
]
(result piped to out.json)

The pipe is not needed when running one single command, and the shell redirection can be used:

./ma-shell.py -k API_KEY_HEX service.list > out.json

Code and License

ma-shell is open source in terms of MIT license and can be obtained for free: https://github.com/memset/ma-shell.