Remove outdated spec/ files. Add github.com/SPORE/specifications link to docs.

3 files changed, 7 insertions, 559 deletions

diff --git a/lib/Net/HTTP/Spore.pm b/lib/Net/HTTP/Spore.pm
index f26f3ff..520b356 100644
--- a/lib/Net/HTTP/Spore.pm
+++ b/lib/Net/HTTP/Spore.pm
@@ -170,7 +170,13 @@ sub _add_methods {
 
 =head1 DESCRIPTION
 
-This module is an implementation of the SPORE specification. To use this client, you need to use or to write a SPORE specification of an API. Some specifications are available L<http://github.com/SPORE/api-description>.
+This module is an implementation of the SPORE specification.
+
+To use this client, you need to use or to write a SPORE specification of an API.
+A description of the SPORE specification format is available at
+L<http://github.com/SPORE/specifications/blob/master/spore_description.pod>
+
+Some specifications for well-known services are available L<http://github.com/SPORE/api-description>.
 
 =head2 CLIENT CREATION
 
diff --git a/spec/spore_description.pod b/spec/spore_description.pod
deleted file mode 100644
index 0feef05..0000000
--- a/spec/spore_description.pod
+++ /dev/null
@@ -1,303 +0,0 @@
-=encoding utf-8
-
-=head1 NAME
-
-Spore (Specifications to a POrtable Rest Environment) 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 descibed API.
-
-This document describes how to write the description for a ReST API in
-order to be used with 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.
-
-=back
-
-=head1 API DESCRIPTION
-
-An API should provide a description file. The description should be in JSON
-format.
-
-XXX all the example should be changes to use valid json fragments instead of yaml.
-I've noted the obvious cases (lists) but the others also need changing to add double quotes etc.
-
-=head2 GENERIC DESCRIPTION
-
-This part describes the API itself:
-
-=head3 name
-
-An optional simple name to describe the specification
-
-    "name" : "CouchDB"
-
-=head3 author
-
-An optional list of authors for this specification
-
-    "author" : [
-      "franck cuny <franck@lumberjaph.net>"
-    ]
-
-XXX should be renamed to be plural?
-
-=head3 api_base_url
-
-An optional base fixed URL for this API
-
-    "api_base_url" : "http://api.twitter.com/1"
-
-Should not including a trailing slash.
-
-=head3 api_format
-
-An optional list of supported formats
-
-    "api_format" : [
-      "json"
-      "xml"
-    ]
-
-XXX what does "supported format" actually mean? What's the effect?
-
-=head3 version
-
-An optional version number for the current description, expressed as a string
-
-    "version" : "0.1"
-
-This is purely for documentation.
-
-=head3 authentication
-
-An optional boolean to specify if this API requires authentication for all the methods
-
-    "authentication" : 1
-
-The default is false.
-
-=head3 methods
-
-A mandatory hash of method names and specifications.
-See L</METHOD DESCRIPTION>.
-
-    "methods" : { ... }
-
-The C<methods> hash B<MUST> contain at least one method.
-
-=head2 METHOD DESCRIPTION
-
-A method must have a name, which is the key in the L</methods> hash
-
-    "methods" : {
-        "public_timeline" : { ... }
-    }
-
-=head3 method
-
-The mandatory C<method> attribute specifies the HTTP method to use for this call
-
-    "method" : "GET"
-
-=head3 path
-
-The mandatory C<path> attribute specifies the URI path for this method.
-
-    "path" : "/login"
-
-The path can contain I<placeholders>. A placeholder
-B<MUST> begin with a <:>:
-
-    "path" : "/statuses/public_timeline.:format"
-
-XXX How can non-placeholder :foo's be included in the path? ie is there an escape mechanism?
-XXX What happens in this example if 'format' isn't listed in params/required?
-XXX What happens if a parameter needs to be followed by a word character? ie can something like :{format}foo be used?
-
-=head3 params
-
-An optional list of I<optional> parameters (contrast with L</required>).
-This list will be used to replace value in placeholders,
-and if not used in the path, will be added to the query.
-
-    "params" : [
-      "trim_user",
-      "include_entities"
-    ]
-
-=head3 required
-
-An optional list of I<required> parameters (contrast with L</params>).
-This list will be used to replace value in placeholders,
-and if not used in the path, will be added to the query.
-
-Parameters that are required B<MUST NOT> be repeated in the B<params> field
-
-    "required" : [
-      "format"
-    ]
-
-=head3 expected
-
-An optional list of valid HTTP response status values for this method
-
-    "expected" : [
-      200,
-      204
-    ]
-
-An exception will be thrown if C<expected> is specified and some other status
-value is returned. Otherwise an exception won't be thrown, even for error status values.
-
-XXX a global api_expected would be handy.
-XXX a global way to express "throw exception for all 4xx and 5xx (unless expected)" would be good.
-
-=head3 description
-
-An optional simple description for the method. This should not be considered as
-documentation.
-
-    "description" : "Returns the 20 most recent statuses, including retweets if they exist, from non-protected users"
-
-=head3 authentication
-
-An optional boolean to specify if this method requires authentication
-
-    "authentication" : 0
-
-The default is false.
-
-=head3 base_url
-
-An optional base url for this method, if different to L</api_base_url>
-
-    "base_url" : "http://api.twitter.com/1"
-
-Should not include a trailing slash.
-
-XXX would be nice to be able to express this as a relative url (relative to api_base_url) That could be handled at build time.
-
-=head3 format
-
-An optional list of supported formats for this method, if different to L</api_format>:
-
-    "format" : [
-      "json",
-      "xml"
-    ]
-
-=head3 documentation
-
-Optional complete documentation text for the method
-
-    "documentation" : "The public timeline is cached for 60 seconds. Requesting more frequently than that will not return any more data, and will count against your rate limit usage."
-
-=head2 SAMPLE
-
-A description for the twitter API (only the API description part and the first method):
-
-    {
-        "api_base_url" : "http://api.twitter.com/1",
-        "version" : "0.1",
-        "methods" : {
-            "public_timeline" : {
-                "params" : [
-                    "trim_user",
-                    "include_entities"
-                ],
-                "required" : [
-                    "format"
-                ],
-                "path" : "/statuses/public_timeline.:format",
-                "method" : "GET"
-            },
-        }
-    }
-
-=head2 CALLS
-
-XXX
-
-=head1 CHANGELOGS
-
-=head2 0.1 - 2010.10.xx
-
-Initial version.
-
-=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
-
-=item Tim Bunce
-
-=back
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright XXX, 2010.
-
-This document is licensed under the Creative Commons license by-sa.
-
-=cut
diff --git a/spec/spore_implementation.pod b/spec/spore_implementation.pod
deleted file mode 100644
index 1e1ee3e..0000000
--- a/spec/spore_implementation.pod
+++ /dev/null
@@ -1,255 +0,0 @@
-=encoding utf-8
-
-=head1 NAME
-
-Spore (Specifications to a POrtable Rest Environment) Client 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 descibed 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 shortcircuit the rest of
-the workflow if needed. It can be thought of 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
-(eg. new_from_spec) to generate the specific API methods in the target
-system by reading the JSON string from a I<Description file> (and
-optionaly directly from the file itself).
-
-A I<Client implementation> B<MUST> also provide a method to enable or
-disable spore middlewares at runtime. The order in which the
-middlewares are enambled  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 postprocessing callback.
-
-  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> 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 shortcicuit the remaining of the chain, for
-testing or caching purpose for exemple.
-
-=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
-schema 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 params.
-
-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 params.
-
-=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 ?, 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. B>MAY> be
-empty but B<MUST> always be present.
-
-=item *
-
-C<spore.scheme>: !!! Check if url_scheme !! The scheme of the url.
-
-
-=item *
-
-C<spore.scheme>: !!! Check if url_scheme !! The scheme of the url.
-
-=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