From 9d0d0bc54c147261e69ce7b28d33454cd225ddb4 Mon Sep 17 00:00:00 2001 From: franck cuny Date: Tue, 12 Oct 2010 14:59:27 +0200 Subject: initial import --- README.md | 11 ++ spore_description.pod | 264 +++++++++++++++++++++++++++++++++++++++++++++++ spore_implementation.pod | 255 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 530 insertions(+) create mode 100644 README.md create mode 100644 spore_description.pod create mode 100644 spore_implementation.pod diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f5a334 --- /dev/null +++ b/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/) \ No newline at end of file diff --git a/spore_description.pod b/spore_description.pod new file mode 100644 index 0000000..f0433e5 --- /dev/null +++ b/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 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 is a library targeting a specific system or +language. It can use I to create programmatic interfaces +usable in applications. + +=item Description file + +A I is a file in JSON format describing an I (see +specification). It can directly be used by a I 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 (optional) + +A simple name to describe the specification + + name: CouchDB + +=item B (optional) + +A list of authors for this specification + + author: + - franck cuny + +=item B (optional) + +If the API has a fixed URL + + api_base_url: http://api.twitter.com/1/ + +=item B (optional) + +A list of supported format + + api_format: + - json + - xml + +=item B (optinal) + +The version number of the current description + + version: 0.1 + +=item B (optional) + +A boolean to specify if this API requires authentication for all the methods + + authentication: 1 + +=item B (required) + +A list of methods + +=back + +The desciption B contain a list of at least one method + +=head2 METHOD DESCRIPTION + +A method must have a name: + + public_timeline + +=over 4 + +=item B (required) + +An HTTP method + + method: GET + +=item B (required) + +Path for the given method. The path can contain B. A placeholder +B begin with a <:>: + + path: /statuses/public_timeline.:format + +=item B (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 (optional) + +A list of required parameters. Parameters that are required B be +repeated in the B field + + required: + - format + +=item B (optional) + +A list of accepted HTTP status for this method + + expected: + - 200 + +=item B (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 (optional) + +A boolean to specify if this method requires authentication + + authentication: 0 + +=item B (optional) + +Specify an url if this method requires a different api_base_url + + api_base_url: http://api.twitter.com/1/ + +=item B (optional) + +A list of supported format + + api_format: + - json + - xml + +=item B (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 + +=item * + +PEP333 Python Web Server Gateway Interface L + +=item * + +Rack L + +=item * + +JSGI Specification L + +=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 diff --git a/spore_implementation.pod b/spore_implementation.pod new file mode 100644 index 0000000..1e1ee3e --- /dev/null +++ b/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 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 is a library targeting a specific system or +language. It can use I to create programmatic interfaces +usable in applications. + +=item Description file + +A I is a file in JSON format describing an I (see +specification). It can directly be used by a I to +create a programmatic interface in the target system. + +=item Middleware + +A I is Spore component that is added to the workflow of +the I to modify the I and +I 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 is a data structure that contains standardized data and +metadata inspired by the CGI specification. It is used by the I to create the http request that will be sent to the +I. + +=item Response + +A I 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 and is used after being processed by +the I to create the structure returned to the user. + +=back + +=head1 SPECIFICATION + +=head2 Client Implementation + +A I B 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 (and +optionaly directly from the file itself). + +A I B 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, I and I were enabled in this order, then + the processing order will be: + I, I, I ... make request ... I, I, I + +=head2 Middleware + +Each middleware B accept arbitrary initialization parameters. It +B 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 be a data structure that includes +CGI-like headers, as detailed below. Each middleware is free to modify +the environment. The environment B include these keys (adopted +from L, +L, +L and +L) except when they would +normally be empty. The environment is used by the I to build the final http request that will be sent to +the I. + +=over 4 + +=item * + +C: The HTTP request method, such as "GET" or +"POST". This B be an empty string, and so is always +required. + +=item * + +C: 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 start with a forward slash (C). + +=item * + +C: 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 start with a forward slash (C). + +=item * + +C: The undecoded, raw request URL line. It is the raw URI +path and query part that appears in the HTTP C 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, C: When combined with C and +C, these keys can be used to complete the URL. Note, +however, that C, if present, should be used in preference +to C for reconstructing the request URL. C +and C B be empty strings, and are always +required. + +=item * + +C: 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: The actual content body of the call. Modified in +place by the middlewares. + +=item * + +C: 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 part of the uri. B>MAY> be +empty but B always be present. + +=item * + +C: !!! Check if url_scheme !! The scheme of the url. + + +=item * + +C: !!! 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 + +=item * + +PEP333 Python Web Server Gateway Interface L + +=item * + +Rack L + +=item * + +JSGI Specification L + +=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 -- cgit v1.2.3