About the description file of an API

[fperrad]

I'll never be happy with a textual specification of this JSON file.
I always prefer a formal description with a schema which allows to use
a verification tool.

So, I try to use Rx, see http://rx.codesimply.com/

And I write my first Rx schema, see below :
(Obviously, this schema needs many refinements)

{
"type": "//rec",
"optional": {
"name": "//str",
"author": "//str",
"api_base_url": "//str",
"api_format": "//str",
"version": "//str",
"authentication": "//bool",
},
"required": {
"methods": {
"type": "//map",
"values": {
"type": "//rec",
"required": {
"method": "//str",
"path": "//str",
},
"optional": {
"params": {
"type": "//arr",
"contents": {
"type": "//str"
},
},
"required": {
"type" : "//arr",
"contents": {
"type": "//str"
},
},
"expected": {
"type" : "//arr",
"contents": {
"type": "//int"
},
},
"description": "//str",
"authentication": "//bool",
"api_base_url": "//str",
"format": "//str",
},
},
},
},
}

The online validator (http://rx.codesimply.com/demo.html) allows to
check the following example :

{
"name": "CouchDB",
"author": "franck cuny <fra...@lumberjaph.net>",
"api_base_url": "http://api.twitter.com/1/",
"api_format": "json",
"version": "0.1",
"authentication": true,
"methods": {
"public_timeline": {
"params" : [
"trim_user",
"include_entities"
],
"required" : [
"format"
],
"path": "/statuses/public_timeline.:format",
"method": "GET"
}
}
}

A small CLI checker could be easily written in Perl5 with Data::Rx.

Another remark, when I added an implementation of a strict mode for
parameter,
I am not happy with the field named "params". I prefer the
complementary pair "required"/"optional".

François

[Nils Grunwald]

2010/10/12 fperrad <fpe...@gmail.com>

I'll never be happy with a textual specification of this JSON file.
I always prefer a formal description with a schema which allows to use
a verification tool.

So, I try to use Rx, see http://rx.codesimply.com/

A small CLI checker could be easily written in Perl5 with Data::Rx.

We could add the schema as additional documentation to the spec, and propose a validator as a convenience tool. We could also automatically validate the schemas that are proposed by users to the central repositery.
 

Another remark, when I added an implementation of a strict mode for
parameter,
I am not happy with the field named "params". I prefer the
complementary pair "required"/"optional".

I see no problem making the change to optional, maybe it will be clearer.

Nils

[franck]

*node*

I will write a validator in Perl with Data::Rx, and won't allow specification that don't pass the check in the repository. 

As for nils, I agree with the modification from 'params' to 'optional'. But maybe we should had a key 'arguments' (or params, not sure what's the best choice):

arguments:

  optional:

    - foo

  required:

    - bar

or keep 'optional' and 'required' at the same level in the method description ?

[Pierre Chapuis]

I didn't know Rx but it's a great tool. This schema will make writing
SPORE descriptions much easier.

The proposed schema doesn't include the most recent modifications of
the spec (title and version are required, ...) though.

Could you put it in Git somewhere (or is it already)?

--
Pierre 'catwell' Chapuis

[franck]

no one is opposed to the changes from

params:

 - foo

required:

 - bar

to 

params:

  optional:

    - foo

  required:

    - bar

?

if every one is OK i'll publish the validator with all the previous modifications and update the current API description.

[julian bilcke]

Hi,

I'm OK with this change, it's more explicit.

Julian

[franck]

I've pushed a schema to validate description: http://github.com/SPORE/specifications/blob/master/spore_validation.rx

I've also updated all current description to reflect recent changes in the spec. They all pass the validation.