An introduction to Wired

This chapter is a small introduction to the WuBook’s API system. The system is developed with the XML-RPC protocol (check the next section for a better description of the protocol itself).

The URL to access the Wired function is https://wubook.net/xrws/ (and notice the final slash: it matters).

Protocol

Many libraries are available for almost all programming languages. Those libraries often allow a very easy development, by completely hiding the XML handling, which is built and sent by the libraries without the need to care about xml formatting.

To better understand this concept, check the following examples:

# python
 >>> import xmlrpclib
 >>> s= xmlrpclib.Server(url)
 >>> res, tok= s.acquire_token(user, pwd, pkey)
/* php */
<?php
  include("xmlrpc.inc");
  $server = new xmlrpc_client($url);
  $args= array(new xmlrpcval($user, 'string'), new xmlrpcval($pass, 'string'), new xmlrpcval($pkey, 'string'));
  $message = new xmlrpcmsg('acquire_token', $args);
  $struct = $server->send($message)->value();
?>
/** java /*
public String getToken(String username, String password, String pkey) throws Exception {
  Vector<String> params = new Vector<String>();
  params.addElement(username);
  params.addElement(password);
  params.addElement(pkey);
  Object[] objects = (Object[]) xmlRpcClient.execute(config, "acquire_token", params);
  return (String) objects[1];
}
# ruby (code provided by Intelligent Mobile, see below)
require 'xmlrpc/client'
token_data = server.call("acquire_token", @config['account_code'], @config['password'], @config['provider_key'])
status = token_data[0]
@token = token_data[1]

Additional information about the XML-RPC protocol? Wikipedia is obviously a good starting point and already lists several well known libraries for each programming language:

If you use Ruby, have a look at the following library, developed by Stefan Eilers (Intelligent Mobile), published on github (here). A gem file is also available there.

So, by using a library you will have to deal with Simple Data (integers, strings, floats and so on), Arrays and Structs. If you don’t want to use an high level library and you want to produce and post XML, make sure to develop propedeutic functions to represent these data types. A good resource is available at this link.

Dates representation

Using Wired means exchanging a lot of information about dates. Dates are almost always sent/received as strings, european format (example: “21/12/2021”). Sometimes, timestamps are used.

XML Examples

As anticipated on the previous section, the XML-RPC protocol has two kind of Data Types: Simple and Complex. Examples of Simple Data Types are string, integers and float. A great part of the callable functions of Wired accepts as arguments only Simple Data Types. For these functions, we will not provide xml examples, because it’s very easy to deduct them.

A generic example will be enough for all of these functions. Let’s consider the following function, requiring as arguments an integer, a string and a float:

sample_function(anInt, aString, aFloat)

If you want to send anInt= 1, aString= “foo” and aFloat= 2.3, the xml which must be produced is:

<?xml version='1.0'?>
<methodCall>
  <methodName>sample_function</methodName>
  <params>
    <param>
      <value><int>1</int></value>
    </param>
    <param>
      <value><string>foo</string></value>
    </param>
    <param>
      <value><double>2.3</double></value>
    </param>
  </params>
</methodCall>

Many Wired functions accept optional arguments. For example, let’s consider the following function:

sample_function(a, b[, c= 1, d= 2])

To call this function, you need to specify at least two arguments: a and b. If you just specify two arguments, the c and the d ones will automatically inherit their default values (1 and 2). If you want to use other values for c and d, you just have to specify them.

Functions using Complex Data are sometimes documented with a dedicated xml example.

Data Types and XML Representations

There are two kind of data types: simple and complex. Simple Data Types are integer, string and float (or double). As Complex Data Types, Wired uses Arrays and Key->Values structures.

Let’s check some examples to better understand the nature of the underlying xml. For Simple Data Types, we have:

<value><int>1</int></value>
<value><double>1.5</double></value>
<value><string>s</string></value>

Arrays can contain arbitrary data types. So, it’s possible to have an Array of Arrays, an Array of strings. It’s also possible to have mixed Arrays. For example, the following one is an array of integers:

<value>
  <array>
    <data>
      <value><int>1</int></value>
      <value><int>2</int></value>
    </data>
  </array>
</value>

Then, let’s check a mixed array (integer and string):

<value>
  <array>
    <data>
      <value><int>1</int></value>
      <value><string>s</string></value>
    </data>
  </array>
</value>

Let’s check now an Array where the second element is an array:

<value>
  <array>
    <data>
      <value><int>1</int></value>
      <value>
        <array>
          <data>
            <value><int>1</int></value>
            <value><int>2</int></value>
          </data>
        </array>
      </value>
    </data>
  </array>
</value>

In the following chapters, arrays are also indicated this way: [1, 2] or [1, [‘a’, ‘b’]].

Key->Values structures are not difficult, too. For example, let’s report a KV struct which associates to a letter its positional value:

<value>
  <struct>
    <member>
      <name>a</name>
      <value><int>1</int></value>
    </member>
    <member>
      <name>b</name>
      <value><int>2</int></value>
    </member>
  </struct>
</value>

KV structs have, as keys, strings. Instead, values can be arbitrary. For example, they can be Arrays or other KV structs.

In the following chapters, KV struct are often represented this way: {‘a’: 1, ‘b’: 2} or {‘a’: 1, ‘b’: [1,2]}

Development and debugging

During the first steps of the development, rely on our collaboration. This is -obviously- the moment when we provide more support to our providers. If you need help, for example because you can’t succesfully call a function, it’s very important to send us the XML you’re sending to our servers.

As stated before, if you use high level libraries, you will probably skip the XML production. However, each library, given a call and its arguments, allows to produce the related xml (instead of automatically producing it under the hood and sending it to the servers).

So, please, as one of your first step, try to understand how to use your library to produce XML without sending it, so that we will be able to help you in the case you will encounter issues.