update specification

1 files changed, 161 insertions, 14 deletions

diff --git a/spec/spore.pod b/spec/spore.pod
index add6922..670f1cf 100644
--- a/spec/spore.pod
+++ b/spec/spore.pod
@@ -1,48 +1,88 @@
+=encoding utf-8
+
 =head1 NAME
 
-Spore - Specifications to a POrtable Rest Environment
+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
+
+=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.
 
-=head1 SYNOPSIS
+=item Description file
 
-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.
+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.
 
 =head1 API DESCRIPTION
 
 An API should provide a description file. The description should be in JSON
 format.
 
-The description can have the following fields:
+=head2 GENERIC DESCRIPTION
+
+This part describes the API itself:
 
 =over 4
 
 =item B<name> (optional)
 
-A simple name to describe the specification (eg: CouchDB)
+A simple name to describe the specification
+
+    name: CouchDB
 
 =item B<author> (optional)
 
 A list of authors for this specification
 
+    author:
+      - franck cuny <franck@lumberjaph.net>
+
 =item B<api_base_url> (optional)
 
 If the API has a fixed URL
 
+    api_base_url: http://api.twitter.com/1/
+
 =item B<api_format> (optional)
 
-A list of supported format (eg: JSON, XML)
+A list of supported format
+
+    api_format:
+      - json
+      - xml
 
 =item B<version> (optinal)
 
 The version number of the current description
 
+    version: 0.1
+
 =item B<authentication> (optional)
 
 A boolean to specify if this API requires authentication for all the methods
 
+    authentication: 1
+
 =item B<methods> (required)
 
 A list of methods
@@ -51,55 +91,162 @@ A list of methods
 
 The desciption B<MUST> contain a list of at least one method
 
+=head2 METHOD DESCRIPTION
+
+A method must have a name:
+
+    public_timeline
+
 =over 4
 
 =item B<method> (required)
 
-An HTTP method (GET/POST/PUT/DELETE)
+An HTTP method
+
+    method: GET
 
 =item B<path> (required)
 
 Path for the given method. The path can contain B<placeholders>. A placeholder
 B<MUST> begin with a <:>:
 
-    /:database
+    path: /statuses/public_timeline.:format
 
 =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
 
+    params:
+      - trim_user
+      - include_entities
+
 =item B<required> (optional)
 
 A list of required parameters. Parameters that are required B<MUST NOT> be
 repeated in the B<params> field
 
+    required:
+      - format
+
 =item B<expected> (optional)
 
-A list of accepted HTTP status for this method. (eg: 200, 201)
+A list of accepted HTTP status for this method
+
+    expected:
+      - 200
 
 =item B<description> (optional)
 
 A simple description for the method. This should not be considered as
 documentation.
 
-    Fetch a document from a CouchDB database
+    description: Returns the 20 most recent statuses, including retweets if they exist, from non-protected users
 
 =item B<authentication> (optional)
 
 A boolean to specify if this method requires authentication
 
+    authentication: 0
+
 =item B<api_base_url> (optional)
 
 Specify an url if this method requires a different api_base_url
 
+    api_base_url: http://api.twitter.com/1/
+
 =item B<documentation> (optional)
 
 A complete documentation for the given 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.
+
 =back
 
 =head3 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"
+            },
+        }
+    }
+
 =head3 CALLS
 
+=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