Resource¶

Kinto-Core provides a basic component to build resource oriented APIs. In most cases, the main customization consists in defining the schema of the records for this resource.

Full example¶

import colander

from kinto.core import resource
from kinto.core import utils


class BookmarkSchema(resource.ResourceSchema):
    url = colander.SchemaNode(colander.String(), validator=colander.url)
    title = colander.SchemaNode(colander.String())
    favorite = colander.SchemaNode(colander.Boolean(), missing=False)
    device = colander.SchemaNode(colander.String(), missing='')

    class Options:
        readonly_fields = ('device',)


@resource.register()
class Bookmark(resource.Resource):
    schema = BookmarkSchema

    def process_object(self, new, old=None):
        new = super().process_object(new, old)
        if new['device'] != old['device']:
            new['device'] = self.request.headers.get('User-Agent')

        return new

See the ReadingList and Kinto projects source code for real use cases.

URLs¶

By default, a resource defines two URLs:

/{classname}s for the list of records
/{classname}s/{id} for single records

Since adding an s suffix for the plural form might not always be relevant, URLs can be specified during registration:

@resource.register(plural_path='/user/bookmarks',
                   object_path='/user/bookmarks/{{id}}')
class Bookmark(resource.Resource):
    schema = BookmarkSchema

Note

The same resource can be registered with different URLs.

Schema¶

Override the base schema to add extra fields using the Colander API.

class Movie(resource.ResourceSchema):
    director = colander.SchemaNode(colander.String())
    year = colander.SchemaNode(colander.Int(),
                               validator=colander.Range(min=1850))
    genre = colander.SchemaNode(colander.String(),
                                validator=colander.OneOf(['Sci-Fi', 'Comedy']))

See the resource schema options to define schema-less resources or specify rules like readonly fields.

HTTP methods and options¶

In order to specify which HTTP verbs (GET, PUT, PATCH, …) are allowed on the resource, as well as specific custom Pyramid (or Cornice) view arguments, refer to the viewset section.

Events¶

When a record is created/deleted in a resource, an event is sent. See the dedicated section about notifications to plug events in your Pyramid/Kinto-Core application or plugin.

Model¶

Plug custom model¶

In order to customize the interaction of a HTTP resource with its storage, a custom model can be plugged-in:

from kinto.core import resource


class TrackedModel(resource.Model):
    def create_record(self, record, parent_id=None):
        record = super().create_record(record, parent_id)
        trackid = index.track(record)
        record['trackid'] = trackid
        return record


class Payment(resource.Resource):
    default_model = TrackedModel

Relationships¶

With the default model and storage backend, Kinto-Core does not support complex relations.

However, it is possible to plug a custom model class, that will take care of saving and retrieving records with relations.

Note

This part deserves more love, please come and discuss!

In Pyramid views¶

In Pyramid views, a request object is available and allows to use the storage configured in the application:

from kinto.core import resource

def view(request):
    registry = request.registry

    flowers = resource.Model(storage=registry.storage,
                             resource_name='app:flowers')

    flowers.create_object({'name': 'Jonquille', 'size': 30})
    flowers.create_object({'name': 'Amapola', 'size': 18})

    min_size = resource.Filter('size', 20, resource.COMPARISON.MIN)
    objects = flowers.get_objects(filters=[min_size])

    flowers.delete_object(records[0])

Outside views¶

Outside views, an application context has to be built from scratch.

As an example, let’s build a code that will copy a collection into another:

from kinto.core import resource, DEFAULT_SETTINGS
from pyramid import Configurator


config = Configurator(settings=DEFAULT_SETTINGS)
config.add_settings({
    'kinto.storage_backend': 'kinto.core.storage.postgresql'
    'kinto.storage_url': 'postgresql://user:pass@db.server.lan:5432/dbname'
})
kinto.core.initialize(config, '0.0.1')

local = resource.Model(storage=config.registry.storage,
                       parent_id='browsing',
                       resource_name='history')

remote = resource.Model(storage=config_remote.registry.storage,
                        parent_id='',
                        resource_name='history')

records, total = in remote.get_records():
for record in records:
    local.create_record(record)

Custom record ids¶

By default, records ids are UUID4.

A custom record ID generator can be set globally in Configuration, or at the resource level:

from kinto.core import resource
from kinto.core import utils
from kinto.core.storage import generators


class MsecId(generators.Generator):
    def __call__(self):
        return '%s' % utils.msec_time()


@resource.register()
class Mushroom(resource.Resource):
    def __init__(request):
        super().__init__(request)
        self.model.id_generator = MsecId()

Python API¶

kinto.core.resource.register(depth=1, **kwargs)¶

Ressource class decorator.

Register the decorated class in the cornice registry. Pass all its keyword arguments to the register_resource function.

Resource¶

class kinto.core.resource.Resource(request, context=None)¶

Resource class providing every HTTP endpoint.

A resource provides all the necessary mechanism for: - storage and retrieval of objects according to HTTP verbs - permission checking and tracking - concurrency control - synchronization - OpenAPI metadata

Permissions are verified in kinto.core.authorization.AuthorizationPolicy based on the verb and context (eg. a put can create or update). The resulting context is passed in the context constructor parameter.

default_viewset¶

Default kinto.core.resource.viewset.ViewSet class to use when the resource is registered.

alias of ViewSet

default_model¶

Default kinto.core.resource.model.Model class to use for interacting the kinto.core.storage and kinto.core.permission backends.

alias of Model

schema¶

Schema to validate objects.

alias of ResourceSchema

permissions = ('read', 'write')¶: List of allowed permissions names.

timestamp¶

Return the current resource timestamp.

Return type:: int

object_id¶: Return the object id for this request. It’s either in the match dict or in the posted body.

get_parent_id(request)¶

Return the parent_id of the resource with regards to the current request.

The resource will isolate the objects from one parent id to another. For example, in Kinto, the group``s and ``collection``s are isolated by ``bucket.

In order to obtain a resource where users can only see their own objects, just return the user id as the parent id:

def get_parent_id(self, request):
    return request.prefixed_userid

Parameters:: request – The request used to access the resource.
Return type:: str

is_known_field(field)¶

Return True if field is defined in the resource schema. If the resource schema allows unknown fields, this will always return True.

Parameters:: field (str) – Field name
Return type:: bool

plural_head()¶

Model HEAD endpoint: empty response with a Total-Objects header.

Raises:: HTTPNotModified if If-None-Match header is provided and collection not modified in the interim.
Raises:: HTTPPreconditionFailed if If-Match header is provided and collection modified in the iterim.
Raises:: HTTPBadRequest if filters or sorting are invalid.

plural_get()¶

Model GET endpoint: retrieve multiple objects.

Raises:: HTTPNotModified if If-None-Match header is provided and the objects not modified in the interim.
Raises:: HTTPPreconditionFailed if If-Match header is provided and the objects modified in the iterim.
Raises:: HTTPBadRequest if filters or sorting are invalid.

plural_post()¶

Model POST endpoint: create an object.

If the new object id conflicts against an existing one, the posted object is ignored, and the existing object is returned, with a 200 status.

Raises:: HTTPPreconditionFailed if If-Match header is provided and the objects modified in the iterim.

Schema¶

class kinto.core.resource.schema.TimeStamp(*args, **kw)¶: This schema is deprecated, you should use kinto.core.schema.TimeStamp instead.

class kinto.core.resource.schema.URL(*args, **kw)¶: This schema is deprecated, you should use kinto.core.schema.URL instead.

class kinto.core.resource.schema.ResourceSchema(*args, **kw)¶

Base resource schema, with Cliquet specific built-in options.

class Options¶

Resource schema options.

This is meant to be overriden for changing values:

class Product(ResourceSchema):
    reference = colander.SchemaNode(colander.String())

    class Options:
        readonly_fields = ('reference',)

readonly_fields = ()¶: Fields that cannot be updated. Values for fields will have to be provided either during object creation, through default values using missing attribute or implementing a custom logic in kinto.core.resource.Resource.process_object().

preserve_unknown = True¶

Define if unknown fields should be preserved or not.

The resource is schema-less by default. In other words, any field name will be accepted on objects. Set this to False in order to limit the accepted fields to the ones defined in the schema.

classmethod is_readonly(field)¶

Return True if specified field name is read-only.

Parameters:: field (str) – the field name in the schema
Returns:: True if the specified field is read-only, False otherwise.
Return type:: bool

schema_type()¶

A type which represents a mapping of names to nodes.

The subnodes of the colander.SchemaNode that wraps this type imply the named keys and values in the mapping.

The constructor of this type accepts one extra optional keyword argument that other types do not: unknown. An attribute of the same name can be set on a type instance to control the behavior after construction.

unknown

unknown controls the behavior of this type when an unknown key is encountered in the cstruct passed to the deserialize method of this instance. All the potential values of unknown are strings. They are:

ignore means that keys that are not present in the schema associated with this type will be ignored during deserialization.
raise will cause a colander.Invalid exception to be raised when unknown keys are present in the cstruct during deserialization.
preserve will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.

Default: ignore.

Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the serialize or deserialize method of this class. In this case, the colander.null value will be passed to the serialize or deserialize method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.

If the colander.null value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.

class kinto.core.resource.schema.PermissionsSchema(*args, **kw)¶

A permission mapping defines ACEs.

It has permission names as keys and principals as values.

{
    "write": ["fxa:af3e077eb9f5444a949ad65aa86e82ff"],
    "groups:create": ["fxa:70a9335eecfe440fa445ba752a750f3d"]
}

deserialize(cstruct=<colander.null>)¶

Deserialize the cstruct into an appstruct based on the schema, run this appstruct through the preparer, if one is present, then validate the prepared appstruct. The cstruct value is deserialized into an appstruct unconditionally.

If appstruct returned by type deserialization and preparation is the value colander.null, do something special before attempting validation:

If the missing attribute of this node has been set explicitly, return its value. No validation of this value is performed; it is simply returned.
If the missing attribute of this node has not been set explicitly, raise a colander.Invalid exception error.

If the appstruct is not colander.null and cannot be validated , a colander.Invalid exception will be raised.

If a cstruct argument is not explicitly provided, it defaults to colander.null.

class kinto.core.resource.schema.HeaderSchema(*args, **kw)¶

Base schema used for validating and deserializing request headers.

static schema_type()¶

A type which represents a mapping of names to nodes.

The subnodes of the colander.SchemaNode that wraps this type imply the named keys and values in the mapping.

The constructor of this type accepts one extra optional keyword argument that other types do not: unknown. An attribute of the same name can be set on a type instance to control the behavior after construction.

unknown

unknown controls the behavior of this type when an unknown key is encountered in the cstruct passed to the deserialize method of this instance. All the potential values of unknown are strings. They are:

ignore means that keys that are not present in the schema associated with this type will be ignored during deserialization.
raise will cause a colander.Invalid exception to be raised when unknown keys are present in the cstruct during deserialization.
preserve will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.

Default: ignore.

Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the serialize or deserialize method of this class. In this case, the colander.null value will be passed to the serialize or deserialize method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.

If the colander.null value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.

class kinto.core.resource.schema.PatchHeaderSchema(*args, **kw)¶: Header schema used with PATCH requests.

class kinto.core.resource.schema.QuerySchema(*args, **kw)¶

Schema used for validating and deserializing querystrings. It will include and try to guess the type of unknown fields (field filters) on deserialization.

static schema_type()¶

A type which represents a mapping of names to nodes.

The subnodes of the colander.SchemaNode that wraps this type imply the named keys and values in the mapping.

The constructor of this type accepts one extra optional keyword argument that other types do not: unknown. An attribute of the same name can be set on a type instance to control the behavior after construction.

unknown

unknown controls the behavior of this type when an unknown key is encountered in the cstruct passed to the deserialize method of this instance. All the potential values of unknown are strings. They are:

ignore means that keys that are not present in the schema associated with this type will be ignored during deserialization.
raise will cause a colander.Invalid exception to be raised when unknown keys are present in the cstruct during deserialization.
preserve will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.

Default: ignore.

Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the serialize or deserialize method of this class. In this case, the colander.null value will be passed to the serialize or deserialize method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.

If the colander.null value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.

deserialize(cstruct=<colander.null>)¶

Deserialize and validate the QuerySchema fields and try to deserialize and get the native value of additional filds (field filters) that may be present on the cstruct.

e.g:: ?exclude_id=a,b&deleted=true -> {‘exclude_id’: [‘a’, ‘b’], deleted: True}

class kinto.core.resource.schema.PluralQuerySchema(*args, **kw)¶: Querystring schema used with plural endpoints.

class kinto.core.resource.schema.ObjectGetQuerySchema(*args, **kw)¶: Querystring schema for GET object requests.

class kinto.core.resource.schema.PluralGetQuerySchema(*args, **kw)¶: Querystring schema for GET plural endpoints requests.

class kinto.core.resource.schema.ObjectSchema(*args, **kw)¶

static schema_type()¶

A type which represents a mapping of names to nodes.

The subnodes of the colander.SchemaNode that wraps this type imply the named keys and values in the mapping.

The constructor of this type accepts one extra optional keyword argument that other types do not: unknown. An attribute of the same name can be set on a type instance to control the behavior after construction.

unknown

unknown controls the behavior of this type when an unknown key is encountered in the cstruct passed to the deserialize method of this instance. All the potential values of unknown are strings. They are:

ignore means that keys that are not present in the schema associated with this type will be ignored during deserialization.
raise will cause a colander.Invalid exception to be raised when unknown keys are present in the cstruct during deserialization.
preserve will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.

Default: ignore.

Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the serialize or deserialize method of this class. In this case, the colander.null value will be passed to the serialize or deserialize method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.

If the colander.null value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.

class kinto.core.resource.schema.JsonPatchOperationSchema(*args, **kw)¶

Single JSON Patch Operation.

static schema_type()¶

A type which represents a mapping of names to nodes.

The subnodes of the colander.SchemaNode that wraps this type imply the named keys and values in the mapping.

The constructor of this type accepts one extra optional keyword argument that other types do not: unknown. An attribute of the same name can be set on a type instance to control the behavior after construction.

unknown

unknown controls the behavior of this type when an unknown key is encountered in the cstruct passed to the deserialize method of this instance. All the potential values of unknown are strings. They are:

ignore means that keys that are not present in the schema associated with this type will be ignored during deserialization.
raise will cause a colander.Invalid exception to be raised when unknown keys are present in the cstruct during deserialization.
preserve will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.

Default: ignore.

Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the serialize or deserialize method of this class. In this case, the colander.null value will be passed to the serialize or deserialize method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.

If the colander.null value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.

class kinto.core.resource.schema.JsonPatchBodySchema(*args, **kw)¶: Body used with JSON Patch (application/json-patch+json) as in RFC 6902.

class kinto.core.resource.schema.RequestSchema(*args, **kw)¶: Base schema for kinto requests.

class kinto.core.resource.schema.PayloadRequestSchema(*args, **kw)¶: Base schema for methods that use a JSON request body.

class kinto.core.resource.schema.JsonPatchRequestSchema(*args, **kw)¶: JSON Patch (application/json-patch+json) request schema.

class kinto.core.resource.schema.ResponseHeaderSchema(*args, **kw)¶: Kinto API custom response headers.

class kinto.core.resource.schema.ErrorResponseSchema(*args, **kw)¶: Response schema used on 4xx and 5xx errors.

class kinto.core.resource.schema.NotModifiedResponseSchema(*args, **kw)¶: Response schema used on 304 Not Modified responses.

class kinto.core.resource.schema.ObjectResponseSchema(*args, **kw)¶: Response schema used with sigle resource endpoints.

class kinto.core.resource.schema.PluralResponseSchema(*args, **kw)¶: Response schema used with plural endpoints.

class kinto.core.resource.schema.ResourceResponses¶

Class that wraps and handles Resource responses.

get_and_bind(endpoint_type, method, **kwargs)¶: Wrap resource colander response schemas for an endpoint and return a dict of status codes mapping cloned and binded responses.

Model¶

class kinto.core.resource.model.Model(storage, permission, id_generator=None, resource_name='', parent_id='', current_principal=None, prefixed_principals=None, explicit_perm=True)¶

A resource stores and manipulate objects in its attached storage.

It is not aware of HTTP environment nor HTTP API.

Objects are isolated according to the provided name and parent_id.

Those notions have no particular semantic and can represent anything. For example, the resource name can be the type of objects stored, and parent_id can be the current user id or a group where the resource belongs. If left empty, the resource objects are not isolated.

id_field = 'id'¶: Name of id field in objects

modified_field = 'last_modified'¶: Name of last modified field in objects

deleted_field = 'deleted'¶: Name of deleted field in deleted objects

timestamp(parent_id=None)¶

Fetch the resource current timestamp.

Parameters:: parent_id (str) – optional filter for parent id
Return type:: int

get_objects(filters=None, sorting=None, pagination_rules=None, limit=None, include_deleted=False, parent_id=None)¶

Fetch the resource objects.

Override to post-process objects after feching them from storage.

Parameters:

filters (list of kinto.core.storage.Filter) – Optionally filter the objects by their attribute. Each filter in this list is a tuple of a field, a value and a comparison (see kinto.core.utils.COMPARISON). All filters are combined using AND.
sorting (list of kinto.core.storage.Sort) – Optionally sort the objects by attribute. Each sort instruction in this list refers to a field and a direction (negative means descending). All sort instructions are cumulative.
pagination_rules (list of list of kinto.core.storage.Filter) – Optionally paginate the list of objects. This list of rules aims to reduce the set of objects to the current page. A rule is a list of filters (see filters parameter), and all rules are combined using OR.
limit (int) – Optionally limit the number of objects to be retrieved.
include_deleted (bool) – Optionally include the deleted objects that match the filters.
parent_id (str) – optional filter for parent id

Returns:

A list of objects in the current page.

Return type:

list

count_objects(filters=None, parent_id=None)¶

Fetch the total count of resource objects

Override to post-process objects after feching them from storage.

Parameters:

filters (list of kinto.core.storage.Filter) – Optionally filter the objects by their attribute. Each filter in this list is a tuple of a field, a value and a comparison (see kinto.core.utils.COMPARISON). All filters are combined using AND.
parent_id (str) – optional filter for parent id

Returns:

An integer of the total number of objects in the result set.

Return type:

int

delete_objects(filters=None, sorting=None, pagination_rules=None, limit=None, parent_id=None)¶

Delete multiple resource objects.

Override to post-process objects after their deletion from storage.

Parameters:

filters (list of kinto.core.storage.Filter) – Optionally filter the objects by their attribute. Each filter in this list is a tuple of a field, a value and a comparison (see kinto.core.utils.COMPARISON). All filters are combined using AND.
sorting (list of kinto.core.storage.Sort) – Optionnally sort the objects by attribute. Each sort instruction in this list refers to a field and a direction (negative means descending). All sort instructions are cumulative.
pagination_rules (list of list of kinto.core.storage.Filter) – Optionnally paginate the deletion of objects. This list of rules aims to reduce the set of objects to the current page. A rule is a list of filters (see filters parameter), and all rules are combined using OR.
limit (int) – Optionnally limit the number of objects to be deleted.
parent_id (str) – optional filter for parent id

Returns:

The list of deleted objects from storage.

get_object(object_id, parent_id=None)¶

Fetch current view related object, and raise 404 if missing.

Parameters:

object_id (str) – object identifier
parent_id (str) – optional filter for parent id

Returns:

the object from storage

Return type:

dict

create_object(obj, parent_id=None)¶

Create an object in the resource.

The current principal is added to the owner (write permission).

Override to perform actions or post-process objects after their creation in storage.

def create_object(self, obj):
    obj = super().create_object(obj)
    idx = index.store(obj)
    object['index'] = idx
    return object

Parameters:

obj (dict) – object to store
parent_id (str) – optional filter for parent id

Returns:

the newly created object.

Return type:

dict

update_object(obj, parent_id=None)¶

Update object and the specified permissions.

If no permissions is specified, the current permissions are not modified.

The current principal is added to the owner (write permission).

Override to perform actions or post-process objects after their modification in storage.

def update_object(self, obj, parent_id=None):
    obj = super().update_object(obj, parent_id)
    subject = f'Object {record[self.id_field]} was changed'
    send_email(subject)
    return object

Parameters:

obj (dict) – object to store
parent_id (str) – optional filter for parent id

Returns:

the updated object.

Return type:

dict

delete_object(obj, parent_id=None, last_modified=None)¶

Delete an object and its associated permissions.

Override to perform actions or post-process objects after deletion from storage for example:

def delete_object(self, obj):
    deleted = super().delete_object(obj)
    erase_media(obj)
    deleted['media'] = 0
    return deleted

Parameters:

obj (dict) – the object to delete
parent_id (str) – optional filter for parent id

Returns:

the deleted object.

Return type:

dict

class kinto.core.resource.model.ShareableModel(*args, **kwargs)¶

Generators¶

class kinto.core.storage.generators.Generator(config=None)¶

Base generator for objects ids.

Id generators are used by storage backend during object creation, and at resource level to validate object id in requests paths.

regexp = '^[a-zA-Z0-9][a-zA-Z0-9_-]*$'¶: Default object id pattern. Can be changed to comply with custom ids.

match(object_id)¶

Validate that object ids match the generator. This is used mainly when an object id is picked arbitrarily (e.g with PUT requests).

Returns:: True if the specified object id matches expected format.
Return type:: bool

class kinto.core.storage.generators.UUID4(config=None)¶

UUID4 object id generator.

UUID block are separated with -. (example: '472be9ec-26fe-461b-8282-9c4e4b207ab3')

UUIDs are very safe in term of unicity. If 1 billion of UUIDs are generated every second for the next 100 years, the probability of creating just one duplicate would be about 50% (source).

regexp = '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'¶: UUID4 accurate pattern.

Resource¶

Full example¶

URLs¶

Schema¶

HTTP methods and options¶

Events¶

Model¶

Plug custom model¶

Relationships¶

In Pyramid views¶

Outside views¶

Custom record ids¶

Python API¶

Resource¶

Schema¶

Model¶

Generators¶

Kinto

Navigation

Related Topics