=head1 NAME

Spore - Specifications to a POrtable Rest Environment

=head1 SYNOPSIS

The ReST
(L<http://en.wikipedia.org/wiki/Representational_State_Transfer|Representational
State Transfer>) paradigm has improved the way we communicate between
services and clients over http. It makes API easy to understand and to implement
client libraries for them.

=head1 API DESCRIPTION

An API should provide a description file. The description should be in JSON
format.

The description can have the following fields:

=over 4

=item B<name> (optional)

A simple name to describe the specification (eg: CouchDB)

=item B<author> (optional)

A list of authors for this specification

=item B<api_base_url> (optional)

If the API has a fixed URL

=item B<api_format> (optional)

A list of supported format (eg: JSON, XML)

=item B<version> (optinal)

The version number of the current description

=item B<authentication> (optional)

A boolean to specify if this API requires authentication for all the methods

=item B<methods> (required)

A list of methods

=back

The desciption B<MUST> contain a list of at least one method

=over 4

=item B<method> (required)

An HTTP method (GET/POST/PUT/DELETE)

=item B<path> (required)

Path for the given method. The path can contain B<placeholders>. A placeholder
B<MUST> begin with a <:>:

    /:database

=item B<params> (optional)

A list of parameters. This list will be used to replace value in placeholders,
and if not used in the path, will be added to the query

=item B<required> (optional)

A list of required parameters. Parameters that are required B<MUST NOT> be
repeated in the B<params> field

=item B<expected> (optional)

A list of accepted HTTP status for this method. (eg: 200, 201)

=item B<description> (optional)

A simple description for the method. This should not be considered as
documentation.

    Fetch a document from a CouchDB database

=item B<authentication> (optional)

A boolean to specify if this method requires authentication

=item B<api_base_url> (optional)

Specify an url if this method requires a different api_base_url

=item B<documentation> (optional)

A complete documentation for the given method

=back

=head3 SAMPLE

=head3 CALLS