API description using cornice and colander ########################################## :status: draft One of the goals we want to accomplish with Cornice is to describe the web services in a nice and easy way, for the developer. This for different reasons. Having web services described in some ways allows you do do interesting things, such as automatically generating a documentation, or a client, for instance. REST services are supposed to be discoverable, but in a lot of situations, that's not the case, and it can be a pain to implement a client for them, even if most of what is being done there is shared between a lot of web services. In cornice, we alreadygenerate some documentation, but this one is incomplete in different ways. For instance, it is currently not possible to get information about the inputs you are waiting for, in the different locations (body, headers and query string). For instance, if you want to describe that a *POST* on `/foobar` needs the *foo* and *bar* parameters, and that you eventually could add a *baz* parameter, you can't, or you have to describe it manually in the documentation of the web service. Cornice, while not tied to `Colander`_, tries to make a good use of it when possible. So it is possible to do validation of the incoming data (in different locations) and, at the same time, documentation of the web service. To do so, you have to use a particular `schema` keyword in the decorator. Here is an example of definition .. code-block:: python from cornice import Service from colander import MappingSchema, SchemaNode, String foobar = Service(name="foobar", path="/foobar") class Foobar(MappingSchema): foo = SchemaNode(String(), location="body") bar = SchemaNode(String(), location="headers") baz = SchemaNode(String(), default=None) @foobar.get(scheme=Foobar) def foobar_get(request): # do something here .. _Colander: http://docs.pylonsproject.org/projects/colander/en/latest/ The output documentation currently looks like this: .. image:: images/cornice-exampledoc-validation.png The plans for the future are to be able to put direct curl calls in the documentation to demonstrate how the service behaves for instance, and why not creating a tiny python client able to consume the cornice APIs.