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
.-
init_app
(app)[source]¶ Flask application initialization.
Initialize the Rate-Limiter, CORS and error handlers.
Parameters: app – An instance of flask.Flask
.
-
init_config
(app)[source]¶ Initialize configuration.
Note
Change Flask-CORS and Flask-Limiter defaults.
Parameters: app – An instance of flask.Flask
.
-
Decorators¶
Decorators for testing certain assertions.
-
invenio_rest.decorators.
require_content_types
(*allowed_content_types)[source]¶ 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.
Errors¶
Exceptions used in Invenio REST module.
-
class
invenio_rest.errors.
FieldError
(field, message, code=None)[source]¶ Represents a field level error.
Note
This is not an actual exception.
Init object.
Parameters: - field – Field name.
- message – The text message to show.
- code – The HTTP status to return. (Default:
None
)
-
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.
-
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.
Constructor.
Parameters: - etag – matching etag
- last_modified – The last modefied date. (Default:
None
)
-
code
= 304¶ HTTP Status code.
-
description
= 'Same Content.'¶ Error description.
Views¶
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 returnflask.Response
instances.Serializing functions can also be overridden by setting
self.serializers
.Parameters: - 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 orNone
.
-
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.
Parameters: 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.
Raises: - werkzeug.exceptions.PreconditionFailed – If the condition is not met.
- invenio_rest.errors.SameContentException – If the the request is GET or HEAD and the If-None-Match condition is not met.
-
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 aflask.Response
, search for the serializing function which matches the best the current request’s Accept header and use it to build theflask.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_method_serializers
(http_method)[source]¶ 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).
Parameters: - serializers – Dictionary of serializers.
- default_media_type – The default media type.
Returns: Best matching serializer based on format query arg first, then client Accept headers or None if no matching serializer.