mirror of
https://github.com/almet/notmyidea.git
synced 2025-04-28 19:42:37 +02:00
58 lines
2.3 KiB
ReStructuredText
58 lines
2.3 KiB
ReStructuredText
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.
|