Custom Accept header routing support for Flask
Project description
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
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
Built Distribution
Hashes for flask_accept-0.0.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e4abfdd2f15b3361992e4f531d666e9104a71a158aca1fdc0d3bda9525e8434c |
|
MD5 | 3dee89455fdba1e14590788fe723f51b |
|
BLAKE2b-256 | 98d6b2ce16b9918002393a366aa62225d4ca544ad23fc23ea92ed1ad3fa6afa8 |