mozilla

Cornice API

This document describes the methods proposed by cornice. It is automatically generated from the source code.

class cornice.service.Service(name, path, description=None, cors_policy=None, depth=1, **kw)

Contains a service definition (in the definition attribute).

A service is composed of a path and many potential methods, associated with context.

All the class attributes defined in this class or in children are considered default values.

Parameters:
  • name – The name of the service. Should be unique among all the services.
  • path – The path the service is available at. Should also be unique.
  • renderer – The renderer that should be used by this service. Default value is ‘simplejson’.
  • description – The description of what the webservice does. This is primarily intended for documentation purposes.
  • validators – A list of callables to pass the request into before passing it to the associated view.
  • filters – A list of callables to pass the response into before returning it to the client.
  • accept – A list of Accept header values accepted for this service (or method if overwritten when defining a method). It can also be a callable, in which case the values will be discovered at runtime. If a callable is passed, it should be able to take the request as a first argument.
  • content_type – A list of Content-Type header values accepted for this service (or method if overwritten when defining a method). It can also be a callable, in which case the values will be discovered at runtime. If a callable is passed, it should be able to take the request as a first argument.
  • factory – A factory returning callables which return boolean values. The callables take the request as their first argument and return boolean values. This param is exclusive with the ‘acl’ one.
  • acl – A callable defining the ACL (returns true or false, function of the given request). Exclusive with the ‘factory’ option.
  • permission – As for pyramid.config.Configurator.add_view. Note: acl and permission can also be applied to instance method decorators such as get() and put().
  • klass – The class to use when resolving views (if they are not callables)
  • error_handler – A callable which is used to render responses following validation failures. Defaults to ‘json_error’.
  • traverse – A traversal pattern that will be passed on route declaration and that will be used as the traversal path.

There are also a number of parameters that are related to the support of CORS (Cross Origin Resource Sharing). You can read the CORS specification at http://www.w3.org/TR/cors/

Parameters:
  • cors_enabled – To use if you especially want to disable CORS support for a particular service / method.
  • cors_origins – The list of origins for CORS. You can use wildcards here if needed, e.g. (‘list’, ‘of’, ‘*.domain’).
  • cors_headers – The list of headers supported for the services.
  • cors_credentials – Should the client send credential information (False by default).
  • cors_max_age – Indicates how long the results of a preflight request can be cached in a preflight result cache.
  • cors_expose_all_headers – If set to True, all the headers will be exposed and considered valid ones (Default: True). If set to False, all the headers need be explicitly mentioned with the cors_headers parameter.
  • cors_policy

    It may be easier to have an external object containing all the policy information related to CORS, e.g:

    >>> cors_policy = {'origins': ('*',), 'max_age': 42,
    ...                'credentials': True}
    

    You can pass a dict here and all the values will be unpacked and considered rather than the parameters starting by cors_ here.

See http://readthedocs.org/docs/pyramid/en/1.0-branch/glossary.html#term-acl for more information about ACLs.

Service cornice instances also have methods get(), post(), put(), options() and delete() are decorators that can be used to decorate views.