Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

initial import

  • Loading branch information...
commit 9d0d0bc54c147261e69ce7b28d33454cd225ddb4 0 parents
@franckcuny franckcuny authored
Showing with 530 additions and 0 deletions.
  1. +11 −0 README.md
  2. +264 −0 spore_description.pod
  3. +255 −0 spore_implementation.pod
11 README.md
@@ -0,0 +1,11 @@
+# SPORE - Specification to a POrtable Rest Environment
+
+## SPECIFICATIONS
+
+ * [API Description](http://github.com/spore/)
+ * [Client Implementation](http://github.com/spore/)
+
+## IMPLEMENTATIONS
+
+ * [Perl](http://github.com/franckcuny/net-http-spore)
+ * [Lua](http://github.com/fperrad/lua-Spore/)
264 spore_description.pod
@@ -0,0 +1,264 @@
+=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.
+
+=head2 GENERIC DESCRIPTION
+
+This part describes the API itself:
+
+=over 4
+
+=item B<name> (optional)
+
+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
+
+ 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
+
+=back
+
+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
+
+ method: GET
+
+=item B<path> (required)
+
+Path for the given method. The path can contain B<placeholders>. A placeholder
+B<MUST> begin with a <:>:
+
+ 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
+
+ expected:
+ - 200
+
+=item B<description> (optional)
+
+A 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
+
+=item B<authentication> (optional)
+
+A boolean to specify if this method requires authentication
+
+ authentication: 0
+
+=item B<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<format> (optional)
+
+A list of supported format
+
+ api_format:
+ - json
+ - xml
+
+=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
255 spore_implementation.pod
@@ -0,0 +1,255 @@
+=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
Please sign in to comment.
Something went wrong with that request. Please try again.