From a8155f9e1b25dc9ac717419531bc64707a416119 Mon Sep 17 00:00:00 2001 From: Tim Bunce Date: Mon, 22 Nov 2010 19:44:47 +0000 Subject: Minor doc updates plus lots of XXX where clarifications are needed --- spec/spore_description.pod | 38 ++++++++++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/spec/spore_description.pod b/spec/spore_description.pod index f0433e5..5d921a9 100644 --- a/spec/spore_description.pod +++ b/spec/spore_description.pod @@ -42,6 +42,9 @@ create a programmatic interface in the target system. An API should provide a description file. The description should be in JSON format. +XXX all the example should be changes to use valid json fragments instead of yaml. +I've noted the obvious cases (lists) but the others also need changing to add double quotes etc. + =head2 GENERIC DESCRIPTION This part describes the API itself: @@ -61,12 +64,16 @@ A list of authors for this specification author: - franck cuny +XXX yaml remnant. should it be an json array? can it be a simple string? + =item B (optional) If the API has a fixed URL api_base_url: http://api.twitter.com/1/ +XXX should it end with "/"? twitter.json doesn't. + =item B (optional) A list of supported format @@ -75,12 +82,16 @@ A list of supported format - json - xml +XXX what does "supported format" actually mean? What's the effect? Is it really a list? + =item B (optinal) The version number of the current description version: 0.1 +XXX clarify type (string/numeric). twitter.json has a string. Any semantics or just for documentation? + =item B (optional) A boolean to specify if this API requires authentication for all the methods @@ -91,13 +102,15 @@ A boolean to specify if this API requires authentication for all the methods A list of methods +XXX list? twitter.json has a hash + =back The desciption B contain a list of at least one method =head2 METHOD DESCRIPTION -A method must have a name: +A method must have a name, which is the key of the C hash described above: public_timeline @@ -111,20 +124,26 @@ An HTTP method =item B (required) -Path for the given method. The path can contain B. A placeholder +Path for the given method. 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? + =item B (optional) -A list of parameters. This list will be used to replace value in placeholders, +A list of optional parameters (also see C below). +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 +XXX yaml + =item B (optional) A list of required parameters. Parameters that are required B be @@ -133,6 +152,8 @@ repeated in the B field required: - format +XXX yaml + =item B (optional) A list of accepted HTTP status for this method @@ -140,6 +161,9 @@ A list of accepted HTTP status for this method expected: - 200 +XXX what are the semantics of this? ie does it mean that 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 @@ -157,13 +181,15 @@ A boolean to specify if this method requires authentication Specify an url if this method requires a different api_base_url - api_base_url: http://api.twitter.com/1/ + base_url: http://api.twitter.com/1/ + +XXX trailing slash? =item B (optional) -A list of supported format +A list of supported formats for this method, if different to C: - api_format: + format: - json - xml -- cgit v1.2.3