zimki | documentation | search
 
Documentation
Zimki Documentation - zimki.publishService

As well as using the built-in Zimki REST/XML methods, you can define your own. Write a function that takes a set of arguments, and call publishService to publish the function as an XML method. The first argument to publishService is the service name for your function. The second argument is the function itself. The third argument is the XML response response format for your function.

For example: 

function myMethod(foo,bar) {
   return {
    text: "Hello, " + foo, 
    number:bar
   };
}

zimki.publishService(
  'my.method.name',
  myMethod,
  '<baz><text>Text goes here</text><number>10</number></baz>',
  { bar: { optional:1 } }
);

The method can then be called as an XML service:

http://service.zimki.com/zimki?api_key=...&method=my.method.name&foo=world&bar=2

Very complicated XML structures can be returned. For more information on defining response structures see the Froody perldoc at http://search.cpan.org/dist/Froody.

The fourth and final argument is a dictionary, the keys of which should by the arguments of your method (the same as the named arguments the function will take). The values of these keys should by objects, the properties of which affect the argument type. For instance, the method above takes a required 'foo' parameter and an optional 'bar' parameter.

The format section tells Zimki how to return the data. Say the data we're sending is an array (named stock) whose items have three elements (name, price, quantity). The format section says:

<list>
    <stock>
      <name>first item</name>
      <price>123.4</price>
      <quantity>12</quantity>
    </stock>
    <stock />
  </list>

<list></list> just tell Zimki to create an XML structure with the top level tags of <list>.

<stock></stock> maps to the stock array which we passed through, and hence Zimki will use the data in this array to populate the XML structure.

<name>, <price> & <quantity> show Zimki how we want the data formatted.

<stock /> is a shortcut; it informs Zimki that there is more than one item in the stock array.

The key thing to understand here is that the format section provides an example for how you want the data formatted and Zimki will try and map the data to that format. We could have used:

<list>
    <stock>
      <name>first item</name>
      <price>123.4</price>
      <quantity>12</quantity>
    </stock>
   <stock>
      <name>first item</name>
      <price>123.4</price>
      <quantity>12</quantity>
    </stock>
</list>

From which Zimki will work out that it is a repeating structure. Equally we could change the order of items, or miss out elements or add our own items.

For example

<list>
    <stock>
     <quantity>12</quantity>
      <price>123.4</price>
    </stock>
    <stock>
     <quantity>12</quantity>
      <price>123.4</price>
    </stock>
</list>

The above only uses the quantity and price elements, and produces

Parent

zimki