Skip to main content

Custom Accept header routing support for Flask

Project description

https://travis-ci.org/di/flask-accept.svg?branch=master

Description

Custom Accept header routing support for Flask.

Features

Respond differently based on the MIME type accepted

Extend any given endpoint to support any additional media type.

Use custom media types to version your API

Never put a /v1/ in your URI ever again.

Dead-simple API

Yet Another Flask Decorator.

Documentation

Installation

Installing:

$ pip install flask-accept

Quickstart

Below is an example Flask app that only accepts the text/html media type:

from flask import Flask
from flask_accept import accept
app = Flask(__name__)

@app.route('/')
@accept('text/html')
def hello_world():
    return 'Hello World!'

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

When one tries to access the endpoint without a valid Accept header:

$ curl localhost:5000 -I
HTTP/1.0 406 NOT ACCEPTABLE

With the valid header:

$ curl localhost:5000 -I -H "Accept: text/html"
HTTP/1.0 200 OK
Content-Type: text/html; charset=utf-8

Adding Support for an Existing Endpoint

Given our example from before, we can add support for a different response to an additonal media type as follows:

from flask import Flask, jsonify
from flask_accept import accept
app = Flask(__name__)

@app.route('/')
@accept('text/html')
def hello_world():
    return 'Hello World!'

@hello_world.support('application/json')
def hello_world_json():
    return jsonify(result="Hello World!")

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

Now our hello_world endpoint supports JSON:

$ curl localhost:5000 -I -H "Accept: application/json"
HTTP/1.0 200 OK
Content-Type: application/json

Falling Back on a Default Endpoint

If we want to support a specific media type, but have every other request fall back to a default endpoint, we can use accept_fallback as follows:

from flask import Flask, jsonify
from flask_accept import accept, accept_fallback
app = Flask(__name__)

@app.route('/')
@accept_fallback
def hello_world():
    return 'Hello World!'

@hello_world.support('application/json')
def hello_world_json():
    return jsonify(result="Hello World!")

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

Our hello_world endpoint still supports JSON, but for any other media type (or if none is specified) it will fall back:

$ curl localhost:5000 -I
HTTP/1.0 200 OK
Content-Type: text/html

$ curl localhost:5000 -I -H "Accept: madeup/mediatype"
HTTP/1.0 200 OK
Content-Type: text/html

Use Cases

Some possible use cases for Flask-Accept.

Versioning your API

Flask-Accept let you accept any possible media type, including custom vendored media types. This is ideal for versioning an API using Accept headers only:

from flask import Flask, jsonify
from flask_accept import accept
app = Flask(__name__)

@app.route('/')
@accept('application/vnd.your_vendor.v1', 'application/vnd.your_vendor.v2')
def hello_world():
    return 'Hello World!'

@hello_world.support('application/vnd.your_vendor.v3')
def hello_world_v2():
    return 'Goodbye cruel world.'

if __name__ == '__main__':
    app.run()
$ curl localhost:5000 -H "Accept: application/vnd.your_vendor.v1"
Hello World!

$ curl localhost:5000 -H "Accept: application/vnd.your_vendor.v2"
Hello World!

$ curl localhost:5000 -H "Accept: application/vnd.your_vendor.v3"
Goodbye cruel world.

Testing

To run the tests

python setup.py test

Authors

License

Open source MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flask_accept-0.0.4.tar.gz (3.9 kB view details)

Uploaded Source

Built Distribution

flask_accept-0.0.4-py3-none-any.whl (5.7 kB view details)

Uploaded Python 3

File details

Details for the file flask_accept-0.0.4.tar.gz.

File metadata

File hashes

Hashes for flask_accept-0.0.4.tar.gz
Algorithm Hash digest
SHA256 e2c636904a2cbff6ca9db5ea70e09be1480b3c2d50ab011d9bfa4d96c7456a4c
MD5 817c633c1f98373f608ab0598b5ff893
BLAKE2b-256 1d34d4f8e174f43c00c2c681c776e3a5340aac0cb478cea4ecc4236583a84a62

See more details on using hashes here.

Provenance

File details

Details for the file flask_accept-0.0.4-py3-none-any.whl.

File metadata

File hashes

Hashes for flask_accept-0.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 e4abfdd2f15b3361992e4f531d666e9104a71a158aca1fdc0d3bda9525e8434c
MD5 3dee89455fdba1e14590788fe723f51b
BLAKE2b-256 98d6b2ce16b9918002393a366aa62225d4ca544ad23fc23ea92ed1ad3fa6afa8

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page