API Schema update

[franck]

Hi all

This weekend with François we added the following keys in the schema:

* expected_status in the API description: you can declare a list of expected status for all your methods, and overload this value per method. (If most of your methods return 200, and only one return 204, you specify the expected_status for this method)

* required_payload at method level: this is a boolean, if set to true, the method must validate that a payload is present

* form-data at method level: see http://gist.github.com/646720.

We also decided to add modularity to API description. You can find an example here http://github.com/SPORE/api-description/tree/master/services/github/ with the github API. An API can be split in various files, and a client should be able to accept multiples description files to build a complete client. 

With the Lua implementation, this is done this way: http://gist.github.com/646721

As always, you can find the schema here: http://github.com/SPORE/specifications/blob/master/spore_validation.rx

If you have any questions or suggestions.

[elishowk]

OK. I wait for the specification to stabilize before finishing
http://github.com/elishowk/pyspore...

On Oct 26, 1:17 pm, franck <fra...@lumberjaph.net> wrote:
> Hi all
>
> This weekend with François we added the following keys in the schema:
>
> * expected_status in the API description: you can declare a list of expected
> status for all your methods, and overload this value per method. (If most of
> your methods return 200, and only one return 204, you specify the
> expected_status for this method)
>
> * required_payload at method level: this is a boolean, if set to true, the
> method must validate that a payload is present
>

> * form-data at method level: seehttp://gist.github.com/646720.

[fperrad]

On Oct 26, 1:17 pm, franck <fra...@lumberjaph.net> wrote:

> Hi all
>
> This weekend with François we added the following keys in the schema:
>
> * expected_status in the API description: you can declare a list of expected
> status for all your methods, and overload this value per method. (If most of
> your methods return 200, and only one return 204, you specify the
> expected_status for this method)
>
> * required_payload at method level: this is a boolean, if set to true, the
> method must validate that a payload is present

for completeness, I propose to add also
optional_payload : boolean

>
> * form-data at method level: seehttp://gist.github.com/646720.
>

in the same way, I propose to add a the field headers with the same
definition that form-data.
the following example comes from CouchDB :
{
"name" : "CouchDB",
"methods" : {
"add_attachment" : {
"path" : "/:db/:id/:file",
"method" : "PUT",
"headers" : {
"Content-Type" : ":content_type"
},
"required_params" : [
"db",
"id",
"rev",
"file",
"content_type"
],
"required_payload" : true
}
}
}

$ curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg?rev=2-2739352689
--data-binary @artwork.jpg -H "Content-Type: image/jpg"
This command becomes in Lua
r = couchdb:add_attachment{
db = 'albums',
id = '6e1295ed6c29495e54cc05947f18c8af',
file = 'artwork.jpg',
rev = '2-2739352689',
content_type = 'image/jpg',
payload = '@artwork.jpg',
}

So, parameters (except payload) could go in HTTP content as form-data,
in HTTP headers, in path & query of the URL.

François.

[franck]

Hi

François: I'm ok to add the "headers" field, as it help to provide a better

description of the API.

I really don't want to add anything that will add constraint to the client 

(like requiring a middleware in the desc; you can *recommand* a middleware in

the meta section, however).