Configuration

Invenio-Records-REST configuration.

invenio_records_rest.config.RECORDS_REST_DEFAULT_CREATE_PERMISSION_FACTORY(*args, **kwargs)

Default create permission factory: reject any request.

invenio_records_rest.config.RECORDS_REST_DEFAULT_DELETE_PERMISSION_FACTORY(*args, **kwargs)

Default delete permission factory: reject any request.

invenio_records_rest.config.RECORDS_REST_DEFAULT_LIST_PERMISSION_FACTORY(*args, **kwargs)

Default list permission factory: allow all requests

invenio_records_rest.config.RECORDS_REST_DEFAULT_LOADERS = {'application/json': <function <lambda>>, 'application/json-patch+json': <function <lambda>>}

Default data loaders per request mime type.

This option can be overritten in each REST endpoint as follows:

RECORDS_REST_ENDPOINTS = {
    'recid': {
        ...
        'record_loaders': {
            'application/json': 'mypackage.utils:myloader',
        },
        ...
    }
}
invenio_records_rest.config.RECORDS_REST_DEFAULT_READ_PERMISSION_FACTORY(record, *args, **kwargs)

Default read permission factory: check if the record exists.

invenio_records_rest.config.RECORDS_REST_DEFAULT_RESULTS_SIZE = 10

Default search results size.

invenio_records_rest.config.RECORDS_REST_DEFAULT_SORT = {'records': {'noquery': 'mostrecent', 'query': 'bestmatch'}}

Default sort option per index with/without query string.

The structure of the dictionary is as follows:

RECORDS_REST_DEFAULT_SORT = {
    '<index or index alias>': {
        'query': '<default-sort-if-a-query-is-passed-from-url>',
        'noquery': '<default-sort-if-no-query-in-passed-from-url>',
    }
}
invenio_records_rest.config.RECORDS_REST_DEFAULT_UPDATE_PERMISSION_FACTORY(*args, **kwargs)

Default update permission factory: reject any request.

invenio_records_rest.config.RECORDS_REST_ELASTICSEARCH_ERROR_HANDLERS = {'query_parsing_exception': 'invenio_records_rest.views:elasticsearch_query_parsing_exception_handler', 'query_shard_exception': 'invenio_records_rest.views:elasticsearch_query_parsing_exception_handler'}

Handlers for ElasticSearch error codes.

invenio_records_rest.config.RECORDS_REST_ENDPOINTS = {'recid': {'default_media_type': 'application/json', 'error_handlers': {}, 'indexer_class': <class 'invenio_indexer.api.RecordIndexer'>, 'item_route': '/records/<pid(recid):pid_value>', 'list_route': '/records/', 'max_result_window': 10000, 'pid_fetcher': 'recid', 'pid_minter': 'recid', 'pid_type': 'recid', 'record_serializers': {'application/json': 'invenio_records_rest.serializers:json_v1_response'}, 'search_class': <class 'invenio_search.api.RecordsSearch'>, 'search_index': None, 'search_serializers': {'application/json': 'invenio_records_rest.serializers:json_v1_search'}, 'search_type': None}}

Default REST endpoints loaded.

This option can be overwritten to describe the endpoints of different record types. Each endpoint is in charge of managing all its CRUD operations (GET, POST, PUT, DELETE, …).

The structure of the dictionary is as follows:

from flask import abort
from flask_security import current_user
from invenio_records_rest.query import es_search_factory
from invenio_records_rest.errors import PIDDeletedRESTError


def search_factory(*args, **kwargs):
    if not current_user.is_authenticated:
        abort(401)
    return es_search_factory(*args, **kwargs)


def permission_check_factory():
    def check_title(record, *args, **kwargs):
        def can(self):
            if record['title'] == 'Hello World':
                return True
        return type('Check', (), {'can': can})()

def deleted_pid_error_handler(error):
    record = error.pid_error.record or {}
    return make_response(jsonify({
        'status': 410,
        'message': error.description,
        'removal_reason': record.get('removal_reason')}), 410)

RECORDS_REST_ENDPOINTS = {
    'endpoint-prefix': {
        'create_permission_factory_imp': permission_check_factory(),
        'default_endpoint_prefix': True,
        'default_media_type': 'application/json',
        'delete_permission_factory_imp': permission_check_factory(),
        'item_route': ('/records/<pid(record-pid-type, '
                       'record_class="mypackage.api:MyRecord"):pid_value>'),
        'links_factory_imp': ('invenio_records_rest.links:'
                              'default_links_factory'),
        'list_route': '/records/',
        'max_result_window': 10000,
        'pid_fetcher': '<registered-pid-fetcher>',
        'pid_minter': '<registered-minter-name>',
        'pid_type': '<record-pid-type>',
        'list_permission_factory_imp': permission_check_factory(),
        'read_permission_factory_imp': permission_check_factory(),
        'record_class': 'mypackage.api:MyRecord',
        'record_loaders': {
            'application/json': 'mypackage.loaders:json_loader'
        },
        'record_serializers': {
            'application/json': 'mypackage.utils:my_json_serializer'
        },
        'record_serializers_aliases': {
            'json': 'application/json'
        },
        'search_class': 'mypackage.utils:mysearchclass',
        'search_factory_imp': search_factory(),
        'search_index': 'elasticsearch-index-name',
        'search_serializers': {
            'application/json': 'mypackage.utils:my_json_search_serializer'
        },
        'search_serializers_aliases': {
            'json': 'application/json'
        },
        'search_type': 'elasticsearch-doc-type',
        'suggesters': {
            'my_url_param_to_complete': {
                '_source': ['specified_source_filtered_field'],
                'completion': {
                    'field': 'suggest_byyear_elasticsearch_field',
                    'size': 10,
                    'context': 'year'
                }
            },
        },
        'update_permission_factory_imp': permission_check_factory(),
        'use_options_view': True,
        'error_handlers': {
            PIDDeletedRESTError: deleted_pid_error_handler,
        },
    },
}
Parameters
  • create_permission_factory_imp – Import path to factory that create permission object for a given record.

  • default_endpoint_prefix – declare the current endpoint as the default when building endpoints for the defined pid_type. By default the default prefix is defined to be the value of pid_type.

  • default_media_type – Default media type for both records and search.

  • delete_permission_factory_imp – Import path to factory that creates a delete permission object for a given record.

  • item_route – URL rule for a single record.

  • links_factory_imp – Factory for record links generation.

  • list_route – Base URL for the records endpoint.

  • max_result_window – Maximum total number of records retrieved from a query.

  • pid_type – It specifies the record pid type. Required. You can generate an URL to list all records of the given pid_type by calling url_for('invenio_records_rest.{0}_list'.format( current_records_rest.default_endpoint_prefixes[pid_type])).

  • pid_fetcher – It identifies the registered fetcher name. Required.

  • pid_minter – It identifies the registered minter name. Required.

  • list_permission_factory_imp – Import path to factory that creates a list permission object for a given index / list.

  • read_permission_factory_imp – Import path to factory that creates a read permission object for a given record.

  • record_class – A record API class or importable string.

  • record_loaders – It contains the list of record deserializers for supported formats.

  • record_serializers – It contains the list of record serializers for supported formats.

  • record_serializers_aliases – A mapping of values of the defined query arg (see config.REST_MIMETYPE_QUERY_ARG_NAME) to valid mimetypes for record item serializers: dict(alias -> mimetype).

  • search_class – Import path or class object for the object in charge of execute the search queries. The default search class is invenio_search.api.RecordsSearch. For more information about resource loading, see the Search <http://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html> of the ElasticSearch DSL library.

  • search_factory_imp – Factory to parse queries.

  • search_index – Name of the search index used when searching records.

  • search_serializers – It contains the list of records serializers for all supported format. This configuration differ from the previous because in this case it handle a list of records resulted by a search query instead of a single record.

  • search_serializers_aliases – A mapping of values of the defined query arg (see config.REST_MIMETYPE_QUERY_ARG_NAME) to valid mimetypes for records search serializers: dict(alias -> mimetype).

  • search_type – Name of the search type used when searching records.

  • suggesters

    Suggester fields configuration. Any element of the dictionary represents a suggestion field. For each suggestion field we can optionally specify the source filtering (appropriate for ES5) by using _source. The key of the dictionary element is used to identify the url query parameter. The field parameter identifies the suggester field name in your elasticsearch schema. To have more information about suggestion configuration, you can read suggesters section on ElasticSearch documentation.

    Note

    Only completion suggesters are supported.

  • update_permission_factory_imp – Import path to factory that creates a update permission object for a given record.

  • use_options_view – Determines if a special option view should be installed.

  • error_handlers – Error handlers configuration for the endpoint. The dictionary has an exception type or HTTP status code as a key and a function or an import path to a function as a value. The function will be passed as an argument to flask.Blueprint.register_error_handler(), so it should take the handled exception/code as its single argument.

invenio_records_rest.config.RECORDS_REST_FACETS = {'records': {'aggs': {'type': {'terms': {'field': 'type'}}}, 'post_filters': {'type': <function terms_filter.<locals>.inner>}}}

Facets per index for the default facets factory.

The structure of the dictionary is as follows:

RECORDS_REST_FACETS = {
    '<index or index alias>': {
        'aggs': {
            '<key>': <aggregation definition>,
            ...
        }
        'filters': {
            '<key>': <filter func>,
            ...
        }
        'post_filters': {
            '<key>': <filter func>,
            ...
        }
    }
}
invenio_records_rest.config.RECORDS_REST_SORT_OPTIONS = {'records': {'bestmatch': {'default_order': 'desc', 'fields': ['_score'], 'order': 1, 'title': 'Best match'}, 'mostrecent': {'default_order': 'asc', 'fields': ['-_created'], 'order': 2, 'title': 'Most recent'}}}

Sort options for default sorter factory.

The structure of the dictionary is as follows:

RECORDS_REST_SORT_OPTIONS = {
    '<index or index alias>': {
        '<sort-field-name>': {
            'fields': ['<search_field>', '<search_field>', ...],
            'title': '<title displayed to end user in search-ui>',
            'default_order': '<default sort order in search-ui>',
        }
    }
}

Each search field can be either:

  • A string of the form '<field name>' (ascending) or '-<field name>' (descending).

  • A dictionary with Elasticsearch sorting syntax (e.g. {'price' : {'order' : 'asc', 'mode' : 'avg'}}).

  • A callable taking one boolean parameter (True for ascending and False for descending) and returning a dictionary like above. This is useful if you need to extract extra sorting parameters (e.g. for geo location searches).