From f7dce1ad7c5e8e63c1dca8f2874986efb8334ca1 Mon Sep 17 00:00:00 2001 From: Tim Bunce Date: Mon, 22 Nov 2010 20:51:25 +0000 Subject: Simplify the element titles to make them easy to link to.Plus other refinements. --- spec/spore_description.pod | 90 +++++++++++++++++++++++++--------------------- 1 file changed, 50 insertions(+), 40 deletions(-) (limited to 'spec') diff --git a/spec/spore_description.pod b/spec/spore_description.pod index 0918d6e..cd702c7 100644 --- a/spec/spore_description.pod +++ b/spec/spore_description.pod @@ -49,15 +49,15 @@ I've noted the obvious cases (lists) but the others also need changing to add do This part describes the API itself: -=head3 B (optional) +=head3 name -A simple name to describe the specification +An optional simple name to describe the specification "name" : "CouchDB" -=head3 B (optional) +=head3 author -A list of authors for this specification +An optional list of authors for this specification "author" : [ "franck cuny " @@ -65,17 +65,17 @@ A list of authors for this specification XXX should be renamed to be plural? -=head3 B (optional) +=head3 api_base_url -If the API has a fixed URL +An optional base fixed URL for this API "api_base_url" : "http://api.twitter.com/1" Should not including a trailing slash. -=head3 B (optional) +=head3 api_format -A list of supported formats +An optional list of supported formats "api_format" : [ "json" @@ -84,55 +84,63 @@ A list of supported formats XXX what does "supported format" actually mean? What's the effect? -=head3 B (optional) +=head3 version -The version number of the current description, expressed as a string +An optional version number for the current description, expressed as a string "version" : "0.1" XXX Any semantics or just for documentation? -=head3 B (optional) +=head3 authentication -A boolean to specify if this API requires authentication for all the methods +An optional boolean to specify if this API requires authentication for all the methods "authentication" : 1 -=head3 B (required) +The default is false. -Specifies the methods to be defined. - - "methods" : { ... } +=head3 methods +A mandatory hash of method descriptions. See L. -The desciption B contain a list of at least one method + "methods" : { ... } + +The C hash B contain at least one method. =head2 METHOD DESCRIPTION -A method must have a name, which is the key in the C hash described above: +A method must have a name, which is the key in the L hash - "public_timeline" : { ... } + "methods" : { + "public_timeline" : { ... } + } -=head3 B (required) +=head3 method -An HTTP method +The mandatory C attribute specifies the HTTP method to use for this call "method" : "GET" -=head3 B (required) +=head3 path + +The mandatory C attribute specifies the URI path for this method. -Path for the given method. The path can contain I. A placeholder + "path" : "/login" + +The path can contain I. A placeholder B 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? -What happens in this example if 'format' isn't listed in params? +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 B (optional) +=head3 params -A list of I parameters (contrast with C). +An optional list of I parameters (contrast with L). This list will be used to replace value in placeholders, and if not used in the path, will be added to the query. @@ -141,9 +149,9 @@ and if not used in the path, will be added to the query. "include_entities" ] -=head3 B (optional) +=head3 required -A list of I parameters (contrast with C). +An optional list of I parameters (contrast with L). This list will be used to replace value in placeholders, and if not used in the path, will be added to the query. @@ -153,9 +161,9 @@ Parameters that are required B be repeated in the B field "format" ] -=head3 B (optional) +=head3 expected -A list of accepted HTTP status for this method +An optional list of valid HTTP response status values for this method "expected" : [ 200, @@ -164,22 +172,24 @@ A list of accepted HTTP status for this method An exception will be thrown if some other status is returned. -=head3 B (optional) +=head3 description -A simple description for the method. This should not be considered as +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 B (optional) +=head3 authentication -A boolean to specify if this method requires authentication +An optional boolean to specify if this method requires authentication "authentication" : 0 -=head3 B (optional) +The default is false. + +=head3 base_url -Specify an url for this method, if different to C +An optional base url for this method, if different to L "base_url" : "http://api.twitter.com/1" @@ -187,18 +197,18 @@ Should not including 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 B (optional) +=head3 format -A list of supported formats for this method, if different to C: +An optional list of supported formats for this method, if different to L: "format" : [ "json", "xml" ] -=head3 B (optional) +=head3 documentation -A complete documentation for the given method +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." -- cgit v1.2.3