Requests

eponvert edited this page Apr 3, 2012 · 6 revisions

Requests

Requests define the possible actions on a resource; both the content of the request and the content of the potential responses are declared as schemas (using Scheme). Requests are primarily identified by their name, though most also specify an HTTP endpoint.

Usage

Requests are declared as inner classes of the resource class, and can inherit from their previous declaration in the previous version of that resource. Requests can declare both valid and error responses, in addition to the standard error responses established by the framework.

Standard requests

Mesh can auto-generate standard CRUD requests for a resource based on its schema. Code can (and generally should) take advantage of this layer by using the classes defined in `mesh.standard`. By default, the following requests are auto-generated:

  • query
  • get
  • create
  • update
  • delete

Limiting the auto-generated requests

A resource can explicitly specify the requests it wants automatically generated, by specifying requests. For example, this resource defines a new request, hello, and explicitly disables auto-generation of the standard requests:

from mesh.standard import *

class HelloWorld(Resource):
    '''Definition of the helloworld resource'''

    name = "helloworld"
    version = 1

    requests = []

    class hello:
        endpoint = (GET, 'hello')
        schema = { 'name': Text()}
        responses = {OK: {'message':Text(required=True, nonnull=True)}}
Another example, this resource is read-only:
from mesh.standard import *

class ReadOnly(Resource):
    name = 'thing'
    version = 1

    requests = ['query', 'get']

    class schema:
        id = Integer(required=True, nonnull=True, operators=['equal'])
        name = Text(required=True, nonnull=True, operators=['equal'])

Overriding the auto-generated requests

A resource can also declare requests which inherit from an auto-generated request, in order to customize it. Example:

class RatherBoring(Resource):
    name = 'ratherboring'
    version = 1
    requests = ['get']
    class get(Resource.get):
        fields = {
            'additional_field': Text()
        }

Operators for the query endpoint

Fields in a schema can be defined with an operators parameter, which hooks the field to the kinds of search operators are available for that field when the resource is queried (i.e. when a request is made of the query endpoint of the resource).

Here's an example.

class Post(Resource):
    '''Definition of a blog post'''

    name = 'post'
    version = 1

    class schema:
        title = Text(operators=['contains'])
        author = Text(operators=['equal'])
        body = Text(operators=['contains'])
        blog = Integer(required=True, nonnull=True, operators=['equal'])
        posted = Datetime(required=True, nonnull=True, operators=['gt', 'gte', 'lt', 'lte'])

The different search operators are:

Operator Comment
equal Equals
iequal Case-insensitive equals
not Not equals
inot Case-insensitive not-equals
prefix Prefix search (field starts with)
iprefix Case-insensitive prefix search
suffix Suffix search (field ends with)
isuffix Case-insensitive suffix search
contains Contains
icontains Case-insensitive contains
gt Greater then
gte Greater then or equal to
lt Less then
lte Less then or equal to
null Is null
in In given values
notin Not in given values