almet/blog.notmyidea.org
1
0
Fork 0
mirror of https://github.com/almet/notmyidea.git synced 2025-04-28 19:42:37 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

fixes

Browse source
This commit is contained in:
Alexis Metaireau 2011-12-07 14:55:07 +01:00
parent 53032588ca
commit 377827749c
1 changed files with 28 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
content/mozilla/introducing-cornice.rst
View file

@ -1,17 +1,17 @@
Introducing cornice
Introducing Cornice
###################
:date: 06/12/2011
Wow, already my third working day at mozilla. Since Monday, I've been working with
Tarek Ziadé, on a pyramid REST-ish toolkit named `cornice <https://github.com/mozilla-services/cornice>`_.
Tarek Ziadé, on a pyramid REST-ish toolkit named `Cornice <https://github.com/mozilla-services/Cornice>`_.
Its goal is to take all the hard bits appart from you when implementing a web
service, so you can focus on what's important. Cornice provides you facilities
Its goal is to take care for you of what you're usually missing so you can
focus on what's important. Cornice provides you facilities
for validation of any kind.
The goal is to simplify your work, but we don't want to reinvent the wheel, so
it is easily pluggable with validations frameworks, such as Collander.
it is easily pluggable with validations frameworks, such as Colander.
Handling errors and validation
==============================
@ -25,7 +25,7 @@ We have changed the way errors are handled. Here is how it works:
def is_awesome(request):
if not 'awesome' in request.GET:
request.errors.add('body', 'awesome',
request.errors.add('query', 'awesome',
'the awesome parameter is required')
@ -36,18 +36,17 @@ We have changed the way errors are handled. Here is how it works:
All the errors collected during the validation process, or after, are collected
before returning the request. If any, a error 400 is fired up, with the list of
problems encoutred encoded as a nice json list (we plan to support multiple
formats in the future)
problems encountered returned as a nice json list response (we plan to support
multiple formats in the future)
As you might have seen, `request.errors.add` takes three parameters: **location**,
**name** and **description**.
**location** is where the error arised. It can either be "body", "query", "headers"
or "path". **name** is the name of the variable causing problem, if any, and
**description** contains a more detailled message.
**location** is where the error is located in the request. It can either be "body",
"query", "headers" or "path". **name** is the name of the variable causing
problem, if any, and **description** contains a more detailled message.
Let's run this simple service, with `bin/paster serve` and send some queries to
it::
Let's run this simple service and send some queries to it::
$ curl -v http://127.0.0.1:5000/service
> GET /service HTTP/1.1
@ -57,7 +56,7 @@ it::
* HTTP 1.0, assume close after body
< HTTP/1.0 400 Bad Request
< Content-Type: application/json; charset=UTF-8
[{"location": "body", "name": "awesome", "description": "You lack awesomeness!"}
[{"location": "query", "name": "awesome", "description": "You lack awesomeness!"}
I've removed the extra clutter from the curl's output, but you got the general idea.
@ -67,8 +66,8 @@ The content returned is in JSON, and I know exactly what I have to do: add an
$ curl http://127.0.0.1:5000/service?awesome=yeah
{"test": "yay!"}
Validators can also attach extra information about validations to the request,
using `request.validated`. It is a standard dict automatically attached to the
Validators can also convert parts of the request and store the converted value
in `request.validated`. It is a standard dict automatically attached to the
requests.
For instance, in our validator, we can chose to validate the parameter passed
@ -81,7 +80,7 @@ and use it in the body of the webservice:
def is_awesome(request):
if not 'awesome' in request.GET:
request.errors.add('body', 'awesome',
request.errors.add('query', 'awesome',
'the awesome parameter is required')
else:
request.validated['awesome'] = 'awesome ' + request.GET['awesome']
@ -91,6 +90,8 @@ and use it in the body of the webservice:
def get1(request):
return {"test": request.validated['awesome']}
The output would look like this:
::
curl http://127.0.0.1:5000/service?awesome=yeah
@ -105,8 +106,8 @@ The HTTP spec defines a **Accept** header the client can send so the response
is encoded the right way. A resource, available at an URL, can be available in
different formats. This is especially true for web services.
Cornice can help you to deal with this. The services you define can tell which
content-types they can deal with, and this will be checked against the
Cornice can help you dealing with this. The services you define can tell which
`Content-Types` values they can deal with and this will be checked against the
**Accept** headers sent by the client.
Let's refine a bit our previous example, by specifying which content-types are
@ -118,8 +119,8 @@ supported, using the `accept` parameter:
def get1(request):
return {"test": "yay!"}
Now, if you specifically ask for XML, for instance, cornice will throw a 406
with the list of accepted content-types::
Now, if you specifically ask for XML, Cornice will throw a 406 with the list of
accepted `Content-Type` values::
$ curl -vH "Accept: application/xml" http://127.0.0.1:5000/service
> GET /service HTTP/1.1
@ -137,3 +138,9 @@ Building your documentation automatically
=========================================
XXX
Yay, how can I get it?
======================
What's next
===========