Flask extension that takes care of API representation and authentication.

Overview

Flask-API-Utils

https://travis-ci.org/marselester/flask-api-utils.png

Flask-API-Utils helps you to create APIs. It makes responses in appropriate formats, for instance, JSON. All you need to do is to return dictionary from your views. Another useful feature is an authentication. The library supports Hawk HTTP authentication scheme and Flask-Login extension. To sum up, there is an API example project.

"Accept" Header based Response

ResponsiveFlask tends to make responses based on Accept request-header (RFC 2616). If a view function does not return a dictionary, then response will be processed as usual. Here is an example.

from api_utils import ResponsiveFlask

app = ResponsiveFlask(__name__)


@app.route('/')
def hello_world():
    return {'hello': 'world'}


def dummy_xml_formatter(*args, **kwargs):
    return '<hello>world</hello>'

xml_mimetype = 'application/vnd.company+xml'
app.response_formatters[xml_mimetype] = dummy_xml_formatter

if __name__ == '__main__':
    app.run()

It's assumed that file was saved as api.py:

$ python api.py
 * Running on http://127.0.0.1:5000/

Here are curl examples with different Accept headers:

$ curl http://127.0.0.1:5000/ -i
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 22
Server: Werkzeug/0.9.4 Python/2.7.5
Date: Sat, 07 Dec 2013 14:01:14 GMT

{
  "hello": "world"
}
$ curl http://127.0.0.1:5000/ -H 'Accept: application/vnd.company+xml' -i
HTTP/1.0 200 OK
Content-Type: application/vnd.company+xml; charset=utf-8
Content-Length: 20
Server: Werkzeug/0.9.4 Python/2.7.5
Date: Sat, 07 Dec 2013 14:01:50 GMT

<hello>world</hello>
$ curl http://127.0.0.1:5000/ -H 'Accept: blah/*' -i
HTTP/1.0 406 NOT ACCEPTABLE
Content-Type: application/json
Content-Length: 83
Server: Werkzeug/0.9.4 Python/2.7.5
Date: Sat, 07 Dec 2013 14:02:23 GMT

{
  "mimetypes": [
    "application/json",
    "application/vnd.company+xml"
  ]
}

HTTP Error Handling

You can set HTTP error handler by using @app.default_errorhandler decorator. Note that it might override already defined error handlers, so you should declare it before them.

from flask import request
from api_utils import ResponsiveFlask

app = ResponsiveFlask(__name__)


@app.default_errorhandler
def werkzeug_default_exceptions_handler(error):
    error_info_url = (
        'http://developer.example.com/errors.html#error-code-{}'
    ).format(error.code)

    response = {
        'code': error.code,
        'message': str(error),
        'info_url': error_info_url,
    }
    return response, error.code


@app.errorhandler(404)
def page_not_found(error):
    return {'error': 'This page does not exist'}, 404


class MyException(Exception):
    pass


@app.errorhandler(MyException)
def special_exception_handler(error):
    return {'error': str(error)}


@app.route('/my-exc')
def hello_my_exception():
    raise MyException('Krivens!')


@app.route('/yarr')
def hello_bad_request():
    request.args['bad-key']

if __name__ == '__main__':
    app.run()

Let's try to curl this example. First response shows that we redefined default {'code': 400, 'message': '400: Bad Request'} error format. Next ones show that you can handle specific errors as usual.

$ curl http://127.0.0.1:5000/yarr -i
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
Content-Length: 125
Server: Werkzeug/0.9.4 Python/2.7.5
Date: Sun, 29 Dec 2013 14:26:30 GMT

{
  "code": 400,
  "info_url": "http://developer.example.com/errors.html#error-code-400",
  "message": "400: Bad Request"
}
$ curl http://127.0.0.1:5000/ -i
HTTP/1.0 404 NOT FOUND
Content-Type: application/json
Content-Length: 41
Server: Werkzeug/0.9.4 Python/2.7.5
Date: Sun, 29 Dec 2013 14:28:46 GMT

{
  "error": "This page does not exist"
}
$ curl http://127.0.0.1:5000/my-exc -i
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 25
Server: Werkzeug/0.9.4 Python/2.7.5
Date: Sun, 29 Dec 2013 14:27:33 GMT

{
  "error": "Krivens!"
}

Authentication

Hawk extension provides API authentication for Flask.

Hawk is an HTTP authentication scheme using a message authentication code (MAC) algorithm to provide partial HTTP request cryptographic verification.

The extension is based on Mohawk, so make sure you have installed it.

$ pip install mohawk

Usage example:

from flask import Flask
from api_utils import Hawk

app = Flask(__name__)
hawk = Hawk(app)


@hawk.client_key_loader
def get_client_key(client_id):
    # In a real project you will likely use some storage.
    if client_id == 'Alice':
        return 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn'
    else:
        raise LookupError()


@app.route('/')
@hawk.auth_required
def index():
    return 'hello world'

if __name__ == '__main__':
    app.run()
$ curl http://127.0.0.1:5000/ -i
HTTP/1.0 401 UNAUTHORIZED
...

Cookie based authentication is disabled by default. Set HAWK_ALLOW_COOKIE_AUTH = True to enable it. Also Hawk supports response signing, enable it HAWK_SIGN_RESPONSE = True if you need it.

Following configuration keys are used by Mohawk library.

HAWK_ALGORITHM = 'sha256'
HAWK_ACCEPT_UNTRUSTED_CONTENT = False
HAWK_LOCALTIME_OFFSET_IN_SECONDS = 0
HAWK_TIMESTAMP_SKEW_IN_SECONDS = 60

Check Mohawk documentation for more information.

It can be convenient to globally turn off authentication when unit testing by setting HAWK_ENABLED = False.

Tests

Tests are run by:

$ pip install -r requirements.txt
$ tox
You might also like...
Rate Limiting extension for Flask

Flask-Limiter Flask-Limiter provides rate limiting features to flask routes. It has support for a configurable backend for storage with current implem

SeaSurf is a Flask extension for preventing cross-site request forgery (CSRF).

Flask-SeaSurf SeaSurf is a Flask extension for preventing cross-site request forgery (CSRF). CSRF vulnerabilities have been found in large and popular

flask extension for integration with the awesome pydantic package

Flask-Pydantic Flask extension for integration of the awesome pydantic package with Flask. Installation python3 -m pip install Flask-Pydantic Basics v

A Flask extension that enables or disables features based on configuration.

Flask FeatureFlags This is a Flask extension that adds feature flagging to your applications. This lets you turn parts of your site on or off based on

A Flask extension that enables or disables features based on configuration.

Flask FeatureFlags This is a Flask extension that adds feature flagging to your applications. This lets you turn parts of your site on or off based on

A Flask extension that enables or disables features based on configuration.

Flask FeatureFlags This is a Flask extension that adds feature flagging to your applications. This lets you turn parts of your site on or off based on

An extension to add support of Plugin in Flask.

An extension to add support of Plugin in Flask.

A nice anonymous messaging api (Uses Flask's restful api)

anonymous-message-api A nice anonymous message api (Uses Flask's restful api) How it works: 1. The user send a put request to your api server: Require

Flask-Rebar combines flask, marshmallow, and swagger for robust REST services.

Flask-Rebar Flask-Rebar combines flask, marshmallow, and swagger for robust REST services. Features Request and Response Validation - Flask-Rebar reli

Comments
  • Bypass hawk authentication if config['TESTING'] is set.

    Bypass hawk authentication if config['TESTING'] is set.

    For writing tests it might be convenient to disable the authentication wrapper if the TESTING config-flag is set. Otherwise tests must implement a fully-fledged Hawk-Client.

    This is also something Flask-Login does. To quote the documentation for @login_required:

    It can be convenient to globally turn off authentication when unit testing. To enable this, if either of the application configuration variables LOGIN_DISABLED or TESTING is set to True, this decorator will be ignored.

    opened by torotil 3
  • Hawk: Support for application/x-www-form-urlencoded

    Hawk: Support for application/x-www-form-urlencoded

    The current implementation of Hawk works fine for application/json, but it doesn't work for urlencoded post data.

    The reason is that (at this time in the request) the form-encoded data can only be accessed in request.form or request.content - while request.data is empty.

    Maybe it would be more robust to move the signature checking into a WSGI-middleware and then access the results later on in the decorators.

    opened by torotil 3
  • Hawk authentication docs

    Hawk authentication docs

    Hi and thanks for publishing this extension.

    I guess I'd need some more information on how the hawk-authentication is supposed to work. I have the basic example up and running. To do something useful I must have answers to at least the following questions:

    • How can I keep track of the currently authenticated "user"?
    • How can I write unit-tests for functionality that depends on having an authenticated user?

    Any suggestions?

    opened by torotil 2
  • Make __all__ a tuple

    Make __all__ a tuple

    Remember, it's the comma that makes a tuple a tuple, not the parens.

    Also, the parens are not required, so you could just write:

    __all__ == "ResponsiveFlask",
    
    opened by attilaolah 1
Owner
Marsel Mavletkulov
I care about architecture and code quality. I like to design web services (APIs) and reason about their boundaries.
Marsel Mavletkulov
Flask-Bcrypt is a Flask extension that provides bcrypt hashing utilities for your application.

Flask-Bcrypt Flask-Bcrypt is a Flask extension that provides bcrypt hashing utilities for your application. Due to the recent increased prevelance of

Max Countryman 282 Feb 11, 2021
flask-apispec MIT flask-apispec (🥉24 · ⭐ 520) - Build and document REST APIs with Flask and apispec. MIT

flask-apispec flask-apispec is a lightweight tool for building REST APIs in Flask. flask-apispec uses webargs for request parsing, marshmallow for res

Joshua Carp 617 Dec 30, 2022
A flask template with Bootstrap 4, asset bundling+minification with webpack, starter templates, and registration/authentication. For use with cookiecutter.

cookiecutter-flask A Flask template for cookiecutter. (Supports Python ≥ 3.6) See this repo for an example project generated from the most recent vers

null 4.3k Dec 29, 2022
A Flask app template with integrated SQLAlchemy, authentication, and Bootstrap frontend

Flask-Bootstrap Flask-Bootstrap is an Flask app template for users to clone and customize as desired, as opposed to a Flask extension that you can ins

Eric S. Bullington 204 Dec 26, 2022
A flask extension using pyexcel to read, manipulate and write data in different excel formats: csv, ods, xls, xlsx and xlsm.

Flask-Excel - Let you focus on data, instead of file formats Support the project If your company has embedded pyexcel and its components into a revenu

null 247 Dec 27, 2022
A Fast API style support for Flask. Gives you MyPy types with the flexibility of flask

Flask-Fastx Flask-Fastx is a Fast API style support for Flask. It Gives you MyPy types with the flexibility of flask. Compatibility Flask-Fastx requir

Tactful.ai 18 Nov 26, 2022
Pf-flask-rest-com - Flask REST API Common Implementation by Problem Fighter Library

In the name of God, the Most Gracious, the Most Merciful. PF-Flask-Rest-Com Docu

Problem Fighter 3 Jan 15, 2022
Flask-template - A simple template for make an flask api

flask-template By GaGoU :3 a simple template for make an flask api notes: you ca

GaGoU 2 Feb 17, 2022
MongoEngine flask extension with WTF model forms support

Flask-MongoEngine Info: MongoEngine for Flask web applications. Repository: https://github.com/MongoEngine/flask-mongoengine About Flask-MongoEngine i

MongoEngine 815 Jan 3, 2023
A caching extension for Flask

Flask-Caching Adds easy cache support to Flask. This is a fork of the Flask-Cache extension. Flask-Caching also includes the cache module from werkzeu

Peter Justin 774 Jan 2, 2023