Flask Helpers¶
As Action Providers are HTTP-servers, a common approach to building them is to use the Flask framework. To aid in developing Flask-based Action Providers, helper methods are provided which encapsulate much of the other functionality in the framework: authentication, validation and serialization for easy use in a Flask-based application. Rather than defining each of the Action Provider Interface routes in the Flask application, helpers are provided which declare the necessary routes to Flask, perform the serialization, validation and authentication on the request, and pass only those requests which have satisfied these conditions on to a user-defined implementation of the routes.
To use the helpers, you must define functions corresponding to the various
methods of the Action Provider interface (run
, status
, release
,
cancel
), and must provide the Action Provider introspection information in
an instance of the ActionProviderDescription
dataclass defined in
the toolkit’s data_types
package. The application must also provide a Flask
blueprint
object to which the toolkit can attach the new routes. It is
recommended that the blueprint
be created with a url_prefix
so that the
Action Provider Interface routes are rooted at a distinct root path in the
application’s URL namespace.
A brief example of setting up the flask helper is provided immediately below. A more complete example showing implementation of all the required functions is provided in the examples/watchasay directory. It is appropriate to use the example as a starting point for any new Action Providers which are developed.
from globus_action_provider_tools.data_types import (
ActionProviderDescription,
ActionRequest,
ActionStatus,
ActionStatusValue,
)
from globus_action_provider_tools.flask import (
ActionStatusReturn,
add_action_routes_to_blueprint,
)
action_blueprint = Blueprint("action", __name__, url_prefix="/action")
provider_description = ActionProviderDescription(
globus_auth_scope="<scope created in Globus Auth>",
title="My Action Provider",
admin_contact="support@example.com",
synchronous=True,
input_schema={}, # JSON Schema representation of the input on the request
log_supported=False
)
add_action_routes_to_blueprint(
action_blueprint,
CLIENT_ID,
CLIENT_SECRET,
CLIENT_NAME,
provider_description,
action_run,
action_status,
action_cancel,
action_release,
)
In this example, the values CLIENT_ID
, CLIENT_SECRET
and CLIENT_NAME
are as defined in Globus Auth as described above (where CLIENT_NAME
is
almost always passed as None
except in the uncommon, legacy case where a
particular name has been associated with a Globus Auth client). The values
action_run
, action_status
, action_cancel
and action_release
are
all functions which will be called by the framework when the corresponding
HTTP requests are called. Where appropriate, these functions are implemented in
terms of the toolkit’s data types so the need for JSON serialization and
deserialization is greatly reduced from the application code. The framework will
also provide validation of input ActionRequest
data to the /run
method
prior to invoking the action_run
function. As long as the return value from
the various functions is of type ActionStatus
, the framework will also
insure that the returned JSON data conforms to the Action Provider Interface.
The watchasay example in the examples/
directory demonstrates how these
functions can be implemented.