From 377827749cf7ece684be597ef187523b7e1f1cc8 Mon Sep 17 00:00:00 2001 From: Alexis Metaireau Date: Wed, 7 Dec 2011 14:55:07 +0100 Subject: [PATCH] fixes --- content/mozilla/introducing-cornice.rst | 49 ++++++++++++++----------- 1 file changed, 28 insertions(+), 21 deletions(-) diff --git a/content/mozilla/introducing-cornice.rst b/content/mozilla/introducing-cornice.rst index de9d206..817b69a 100644 --- a/content/mozilla/introducing-cornice.rst +++ b/content/mozilla/introducing-cornice.rst @@ -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 `_. +Tarek Ziadé, on a pyramid REST-ish toolkit named `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 +===========