API Docs

REST API module for Invenio.

class invenio_rest.ext.InvenioREST(app=None)[source]

Invenio-REST extension.

Extension initialization.

Parameters:app – An instance of flask.Flask.

Flask application initialization.

Initialize the Rate-Limiter, CORS and error handlers.

Parameters:app – An instance of flask.Flask.

Initialize configuration.


Change Flask-CORS and Flask-Limiter defaults.

Parameters:app – An instance of flask.Flask.


Decorators for testing certain assertions.


Decorator to test if proper Content-Type is provided.

Parameters:*allowed_content_types – List of allowed content types.
Raises:invenio_rest.errors.InvalidContentType – It’s rised if a content type not allowed is required.


Exceptions used in Invenio REST module.

class invenio_rest.errors.FieldError(field, message, code=None)[source]

Represents a field level error.


This is not an actual exception.

Init object.

  • field – Field name.
  • message – The text message to show.
  • code – The HTTP status to return. (Default: None)

Convert to dictionary.

Returns:A dictionary with field, message and, if initialized, the HTTP status code.
exception invenio_rest.errors.InvalidContentType(allowed_content_types=None, **kwargs)[source]

Error for when an invalid Content-Type is provided.

Initialize exception.

code = 415

HTTP Status code.

exception invenio_rest.errors.RESTException(errors=None, **kwargs)[source]

HTTP Exception delivering JSON error responses.

Initialize RESTException.


Get the request body.


Get the description.


Get errors.

Returns:A list containing a dictionary representing the errors.

Get a list of headers.

exception invenio_rest.errors.RESTValidationError(errors=None, **kwargs)[source]

A standard REST validation error.

Initialize RESTException.

code = 400

HTTP Status code.

description = 'Validation error.'

Error description.

exception invenio_rest.errors.SameContentException(etag, last_modified=None, **kwargs)[source]

304 Same Content exception.

Exception thrown when request is GET or HEAD, ETag is If-None-Match and one or more of the ETag values match.


  • etag – matching etag
  • last_modified – The last modefied date. (Default: None)
code = 304

HTTP Status code.

description = 'Same Content.'

Error description.


Get a list of headers.


REST API module for Invenio.

class invenio_rest.views.ContentNegotiatedMethodView(serializers=None, method_serializers=None, serializers_query_aliases=None, default_media_type=None, default_method_media_type=None, *args, **kwargs)[source]

MethodView with content negotiation.

Dispatch HTTP requests as MethodView does and build responses using the registered serializers. It chooses the right serializer using the request’s accept type. It also provides a helper method for handling ETags.

Register the serializing functions.

Serializing functions will receive all named and non named arguments provided to make_response or returned by request handling methods. Recommended prototype is: serializer(data, code=200, headers=None) and it should return flask.Response instances.

Serializing functions can also be overridden by setting self.serializers.

  • serializers – A mapping from mediatype to a serializer function.
  • method_serializers – A mapping of HTTP method name (GET, PUT, PATCH, POST, DELETE) -> dict(mediatype -> serializer function). If set, it overrides the serializers dict.
  • serializers_query_aliases – A mapping of values of the defined query arg (see config.REST_MIMETYPE_QUERY_ARG_NAME) to valid mimetypes: dict(alias -> mimetype).
  • default_media_type – Default media type used if no accept type has been provided and global serializers are used for the request. Can be None if there is only one global serializer or None. This media type is used for method serializers too if default_method_media_type is not set.
  • default_method_media_type – Default media type used if no accept type has been provided and a specific method serializers are used for the request. Can be None if the method has only one serializer or None.
check_etag(etag, weak=False)[source]

Validate the given ETag with current request conditions.

Compare the given ETag to the ones in the request header If-Match and If-None-Match conditions.

The result is unspecified for requests having If-Match and If-None-Match being both set.


etag (str) – The ETag of the current resource. For PUT and PATCH it is the one before any modification of the resource. This ETag will be tested with the Accept header conditions. The given ETag should not be quoted.

check_if_modified_since(dt, etag=None)[source]

Validate If-Modified-Since with current request conditions.

dispatch_request(*args, **kwargs)[source]

Dispatch current request.

Dispatch the current request using flask.views.MethodView dispatch_request() then, if the result is not already a flask.Response, search for the serializing function which matches the best the current request’s Accept header and use it to build the flask.Response.

Return type:flask.Response
Raises:werkzeug.exceptions.NotAcceptable – If no media type matches current Accept header.
Returns:The response returned by the request handler or created by the serializing function.

Get request method serializers + default media type.

Grab serializers from method_serializers if defined, otherwise returns the default serializers. Uses GET serializers for HEAD requests if no HEAD serializers were specified.

The method also determines the default media type.

Parameters:http_method – HTTP method as a string.
Returns:Tuple of serializers and default media type.
make_response(*args, **kwargs)[source]

Create a Flask Response.

Dispatch the given arguments to the serializer best matching the current request’s Accept header.

Returns:The response created by the serializing function.
Return type:flask.Response
Raises:werkzeug.exceptions.NotAcceptable – If no media type matches current Accept header.
match_serializers(serializers, default_media_type)[source]

Choose serializer for a given request based on query arg or headers.

Checks if query arg format (by default) is present and tries to match the serializer based on the arg value, by resolving the mimetype mapped to the arg value. Otherwise, chooses the serializer by retrieving the best quality Accept headers and matching its value (mimetype).

  • serializers – Dictionary of serializers.
  • default_media_type – The default media type.

Best matching serializer based on format query arg first, then client Accept headers or None if no matching serializer.


Create an API error handler.

E.g. register a 404 error:

    status=404, message='Not Found'))
Parameters:**kwargs – It contains the 'status' and the 'message' to describe the error.