blob: 3cd44d14dde8b286ee162ab0b8de0196e8317315 (
plain) (
tree)
|
|
=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 have improved the way we communicate between
services and clients. It's easy to understand an API and to implement
the communications.
=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 have a fixed URL
=item B<api_format> (optional)
A list of supported format (eg: JSON, XML)
=item B<version> (optinal)
A version of the current description
=item B<authentication> (optional)
A boolean to inform if this API require authentication for all the methods
=item B<methods> (required)
A list of methods
=back
The desciption B<MUST> contains 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 contains B<placeholder>. A placeholder
B<MUST> begins with a <:>:
/:database
=item B<params> (optional)
A list of parameters. This list will be used to replace value in placeholder,
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
repeted 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 define if this method requires authentication
=item B<api_base_url> (optional)
If this method require a different api_base_url
=item B<documentation> (optional)
A complete documentation for the given method
=back
=head3 SAMPLE
=head3 CALLS
|
