From 6d00432bb89190a6d7ff757aaaa9ffa5021e3794 Mon Sep 17 00:00:00 2001 From: Tim Bunce Date: Mon, 22 Nov 2010 20:32:20 +0000 Subject: Convert examples to JSON. Refine/extend some docs. --- spec/spore_description.pod | 105 +++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 47 deletions(-) diff --git a/spec/spore_description.pod b/spec/spore_description.pod index 5d921a9..7cbbeea 100644 --- a/spec/spore_description.pod +++ b/spec/spore_description.pod @@ -55,54 +55,58 @@ This part describes the API itself: A simple name to describe the specification - name: CouchDB + "name" : "CouchDB" =item B (optional) A list of authors for this specification - author: - - franck cuny + "author" : [ + "franck cuny " + ] -XXX yaml remnant. should it be an json array? can it be a simple string? +XXX should be renamed to be plural? =item B (optional) If the API has a fixed URL - api_base_url: http://api.twitter.com/1/ + "api_base_url" : "http://api.twitter.com/1" -XXX should it end with "/"? twitter.json doesn't. +Should not including a trailing slash. =item B (optional) -A list of supported format +A list of supported formats - api_format: - - json - - xml + "api_format" : [ + "json" + "xml" + ] -XXX what does "supported format" actually mean? What's the effect? Is it really a list? +XXX what does "supported format" actually mean? What's the effect? -=item B (optinal) +=item B (optional) -The version number of the current description +The version number of the current description, expressed as a string - version: 0.1 + "version" : "0.1" -XXX clarify type (string/numeric). twitter.json has a string. Any semantics or just for documentation? +XXX Any semantics or just for documentation? =item B (optional) A boolean to specify if this API requires authentication for all the methods - authentication: 1 + "authentication" : 1 =item B (required) -A list of methods +Specifies the methods to be defined. -XXX list? twitter.json has a hash + "methods" : { ... } + +See L. =back @@ -110,9 +114,9 @@ The desciption B contain a list of at least one method =head2 METHOD DESCRIPTION -A method must have a name, which is the key of the C hash described above: +A method must have a name, which is the key in the C hash described above: - public_timeline + "public_timeline" : { ... } =over 4 @@ -120,84 +124,89 @@ A method must have a name, which is the key of the C hash described abo An HTTP method - method: GET + "method" : "GET" =item B (required) Path for the given method. The path can contain I. A placeholder B begin with a <:>: - path: /statuses/public_timeline.:format + "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? =item B (optional) -A list of optional parameters (also see C below). +A list of I parameters (contrast with C). 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 +and if not used in the path, will be added to the query. -XXX yaml + "params" : [ + "trim_user", + "include_entities" + ] =item B (optional) -A list of required parameters. Parameters that are required B be -repeated in the B field +A list of I parameters (contrast with C). +This list will be used to replace value in placeholders, +and if not used in the path, will be added to the query. - required: - - format +Parameters that are required B be repeated in the B field -XXX yaml + "required" : [ + "format" + ] =item B (optional) A list of accepted HTTP status for this method - expected: - - 200 + "expected" : [ + 200, + 204 + ] -XXX what are the semantics of this? ie does it mean that an exception will be -thrown if some other status is returned? +An exception will be thrown if some other status is returned. =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 + "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 + "authentication" : 0 =item B (optional) -Specify an url if this method requires a different api_base_url +Specify an url for this method, if different to C - base_url: http://api.twitter.com/1/ + "base_url" : "http://api.twitter.com/1" -XXX trailing slash? +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. =item B (optional) A list of supported formats for this method, if different to C: - format: - - json - - xml + "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. + "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 @@ -279,6 +288,8 @@ I'd like to thank authors of these great documents. =item damien "bl0b" leroux +=item Tim Bunce + =back =head1 COPYRIGHT AND LICENSE -- cgit 1.4.1