NAME

Froody::API::XML - Define a Froody API with xml

SYNOPSIS

  package MyAPI;
  use base qw{Froody::API::XML};
  
  sub xml { 
    return q{
      <spec>
        <methods>
          <method name="foo">....</method>
        </methods>
      </spec>
    };
   }
   
   1;

DESCRIPTION

This class is a helper base class for Froody::API. It can parse a standard format of XML and turn it into a bunch of Froody::Method objects.

METHODS

xml

Subclasses must override this method to provide an XML specification.

load( xml )

Calls load_spec() with the return value of the xml method.

load_spec($xml_string)

Turns a method spec xml string into an array of Froody::Method objects.

load_method($element)

Passed an XML::LibXML::Element that represents a <method>...</method>, this returns an instance of Froody::Method that represents that method.

load_errortype

Passed an XML::LibXML::Element that represents an <errortype>...</errortype>, this returns an instance of Froody::ErrorType that represents that error type.

parser

This method returns the parser we're using. It's an instance of XML::LibXML.

SPEC OVERVIEW

The specs handed to register_spec() should be on this form:

  <spec>
    <methods>
      <method ...> </method>
      ...
    </methods>
    <errortypes>
       <errortype code="error.subtype">...</errortype>
       ...
    </errortypes>
  </spec>

<method>

Each method take this form:

  <method name="foo.bar.quux" needslogin="1">
    <description>Very short description of method's basic behaviour</description>
    <keywords>...</keywords>
    <arguments>...</arguments>
    <response>...</response>
    <errors>...</errors>
  </method>

<keywords>

A space-separated list of keywords of the concepts touched upon by this method. As an example, clockthat.events.addTags would have "events tags" as its keywords. This way we can easily list all methods that deals with tags, no matter where in the namespace they live.

<arguments>

Each argument has two mandatory attributes: "name" and "optional". The name is the name of the argument, and optional is "1" if the argument is optional, or "0" otherwise.

  <argument name="api_key" optional="0">A non-optional argument</argument>
  <argument name="quux_id" optional="1">An optional argument</argument>

You can specify that your argument should accept a comma-separated list of values:

  <argument name="array_val" type="csv" optional="1">Don't
    worry about description for argument type deduction now.</argument>

<response>

A well-formed XML fragment (excluding the <rsp> tag) describing by example how this method will respond. This section can be empty if the method does not return. When a list of elements are expected, your example response must contain at least two elements of the same name.

  <photoset page="1" per_page="10" pages="9" total="83">
    <name>beyond repair</name>
    <photo photo_id="1123" />
    <photo photo_id="2345" />
  </photos>

Currently we accept both a well-formed XML fragment and an entity-encoded string that can be decoded to an XML fragment.

<errors>

A list of errors of this form:

  <error code="1" message="Short message">Longer error message</error>

BUGS

None known.

Please report any bugs you find via the CPAN RT system. http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Froody

AUTHOR

Copyright Fotango 2005. All rights reserved.

Please see the main Froody documentation for details of who has worked on this project.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Froody