From d8c365c4e2138ad89a44ac6db8160feffebd5f68 Mon Sep 17 00:00:00 2001 From: franck cuny Date: Wed, 15 Sep 2010 14:10:50 +0200 Subject: remove and renamed --- spec/spore.pod | 252 --------------------------------------------------------- 1 file changed, 252 deletions(-) delete mode 100644 spec/spore.pod (limited to 'spec/spore.pod') diff --git a/spec/spore.pod b/spec/spore.pod deleted file mode 100644 index 670f1cf..0000000 --- a/spec/spore.pod +++ /dev/null @@ -1,252 +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 - -=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. - -=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 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 -- cgit v1.2.3