Requests

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