As per my discussions on IRC with Dan, and looking at some recent patches,
here are the points I plan to include in the doc:
Routing applications: The Flask application instance, 'app'
needs to be imported from bkr.server.wsgi and then the view function
can be exposed by decorating it with @app.route(). You can also
specify the HTTP methods which the view can handle using the methods
keyword argument.
Example: @app.route('/systems/<fqdn>/access-policy',
methods=['POST', 'PUT'])
To learn more:
http://flask.pocoo.org/docs/api/#url-route-registrations
Identity checking: If a view function needs authentication,
it can be checked using bkr.server.identity
UI Feedback: Although Flask has it's own mechanism for flash messages,
you must use Turbogears's flash() method
Retuning data: Use Flask's jsonify() function to return your response
as JSON data.
To learn more:
http://flask.pocoo.org/docs/api/#module-flask.json
Aborting: If something is not right, use the abort() function
to raise a HTTPException. For eg, abort(401) would indicate a
authentication failure.
To learn more:
http://flask.pocoo.org/docs/api/#flask.abort
Returning empty response: If the view function has nothing to return,
return an empty string with a status code, like so: return '', 204
Comments, suggestions welcome.
Thanks,
Amit.