=encoding utf-8

=head1 NAME

Spore (B<S>pecifications to a B<Po>rtable B<R>EST B<E>nvironment) Description Implementation

=head1 ABSTRACT

Spore is a specification for describing REST API that can be parsed and used
automatically by client implementations to communicate with the described API.

This document describes what features are required in a Spore client
implementation.

=head1 TERMINOLOGY

=over 4

=item API

An I<API> is a REST application that can exchange data with client
applications over HTTP/HTTPS. It presents one or more method endpoints which
accept HTTP requests with varying headers, parameters and body content to
perform specific operations.

=item Client implementation

A I<Client implementation> is a library targeting a specific system or
language. It can use I<Descriptions files> to create programmatic interfaces
usable in applications.

=item Description file

A I<Description file> is a file in JSON format describing an I<API> (see
specification). It can directly be used by a  I<Client implementation> to
create a programmatic interface in the target system.

=item Middleware

A I<Middleware> is Spore component that is added to the workflow of
the I<Client implementation> to modify the I<Requests> and
I<responses> sent and received. It can also shortcut the rest of
the workflow if needed. It can be thought of as a plugin to extend Spore.

=item Request

A I<Request> is a data structure that contains standardized data and
metadata inspired by the CGI specification. It is used by the I<Client
implementation> to create the HTTP request that will be sent to the
I<API>.

=item Response

A I<Response> is a data structure that contains standardized data and
metadata inspired by the CGI specification. It is created from the
HTTP response sent by the I<API> and is used after being processed by
the I<Middlewares> to create the structure returned to the user.

=back

=head1 SPECIFICATION

=head2 Client Implementation

A I<Client implementation> B<MUST> provide a function or method
(e.g. new_from_spec) to generate the specific API methods in the target
system by reading the JSON string from a I<Description file> (and
optionally directly from the file itself).

A I<Client implementation> B<MUST> also provide a method to enable or
disable spore middlewares at run-time. The order in which the
middlewares are enabled is the order in which the request will go
through each middleware, and the inverse order in which the response
will go through each optional middleware post-processing callback. It
B<MUST> also have a method to selectively enable a middleware or not
for each method according to the method properties in the
specification.

  If middlewares I<A>, I<B> and I<C> were enabled in this order, then
  the processing order will be:
    I<A>, I<B>, I<C> ... make request ... I<C>, I<B>, I<A>

=head2 Middleware

Each middleware B<MUST> accept arbitrary initialization parameters. It
B<MUST> provide a way to only conditionally use a middleware (e.g. B<enable_if>). It
B<MUST> also provide a function to which the request environment or an
object containing it will be passed. The function can have 3 types of
return values:

=over 4

=item Nothing

Control is passed to the next middleware in the chain.

=item A callback

Control is passed to the next middleware in the chain. The callback is
stored and will be passed the response later on after the request is
made.

=item A response

The response is directly passed to the first stored callback in the
chain. No further middlewares are used and no request is sent. Useful
if a middleware needs to short-circuit the remaining of the chain, for
testing or caching purpose for example.

=back

=head3 The Request environment

The request environment B<MUST> be a data structure that includes
CGI-like headers, as detailed below. Each middleware is free to modify
the environment. The environment B<MUST> include these keys (adopted
from L<PEP 333|http://www.python.org/dev/peps/pep-0333/>,
L<Rack|http://rack.rubyforge.org/doc/files/SPEC.html>,
L<PSGI|http://search.cpan.org/perldoc?PSGI> and
L<JSGI|http://jackjs.org/jsgi-spec.html>) except when they would
normally be empty. The environment is used by the I<Client
implementation> to build the final HTTP request that will be sent to
the I<API>.

=over 4

=item *

C<REQUEST_METHOD>: The HTTP request method, such as "GET" or
"POST". This B<MUST NOT> be an empty string, and so is always
required.

=item *

C<SCRIPT_NAME>: The initial portion of the base URL's path, minus the
scheme and domain name. This tells the client what is the API virtual
"location". This may be an empty string if the method corresponds to
the server's root URI.

If this key is not empty, it B<MUST> start with a forward slash (C</>).

=item *

C<PATH_INFO>: The remainder of the request URL's path, designating the
virtual "location" of the request's target within the API. This may be
an empty string if the request URL targets the application root and
does not have a trailing slash. It still contains the placeholders
which will be interpolated later with the parameters.

If this key is not empty, it B<MUST> start with a forward slash (C</>).

=item *

C<REQUEST_URI>: The undecoded, raw request URL line. It is the raw URI
path and query part that appears in the HTTP C<GET /... HTTP/1.x> line
and doesn't contain URI scheme and host names. It still contains the
placeholders which will be interpolated later with the parameters.

=item *

C<SERVER_NAME>, C<SERVER_PORT>: When combined with C<SCRIPT_NAME> and
C<PATH_INFO>, these keys can be used to complete the URL. Note,
however, that C<HTTP_HOST>, if present, should be used in preference
to C<SERVER_NAME> for reconstructing the request URL. C<SERVER_NAME>
and C<SERVER_PORT> B<MUST NOT> be empty strings, and are always
required.

=item *

C<QUERY_STRING>: The portion of the request URL that follows the C<?>, if
any. May be empty, but is always required. It will always be empty
before the request is actually made and sent.

=item *

C<spore.payload>: The actual content body of the call. Modified in
place by the middlewares.

=item *

C<spore.params>: A list of key/value pairs. These will be interpolated
in the URL with the placeholders when the request is made. The rest of
them will be used in the C<QUERY_STRING> part of the URI and the
payload key will define the actual content. B<MAY> be empty but
B<MUST> always be present.

=item *

C<spore.redirections>: An ordered list of all the intermediate URL that
were tried by the fetcher.

=item *

C<spore.scheme>: The scheme of the URL.

=item *

C<spore.expected_status>: The list of expected HTTP statuses for this request in the response.

=back

=head1 CHANGELOGS

0.1: 2010.10.xx

=over 4

=item *

Initial version.

=back

=head1 ACKNOWLEDGEMENTS

Some parts of this specification are adopted from the following specifications.

=over 4

=item *

PSGI Specification L<PSGI|http://search.cpan.org/perldoc?PSGI>

=item *

PEP333 Python Web Server Gateway Interface L<http://www.python.org/dev/peps/pep-0333>

=item *

Rack L<http://rack.rubyforge.org/doc/SPEC.html>

=item *

JSGI Specification L<http://jackjs.org/jsgi-spec.html>

=back

I'd like to thank authors of these great documents.

=head1 AUTHOR

=over 4

=item franck cuny

=item nils grunwald

=back

=head1 CONTRIBUTORS

=over 4

=item damien "bl0b" leroux

=back

=head1 COPYRIGHT AND LICENSE

Copyright XXX, 2010.

This document is licensed under the Creative Commons license by-sa.

=cut