HAL extension for Flask-RESTful
Project description
Introduction
Flask-RESTful-HAL is an extension for Flask-RESTful. It adds support for building HAL APIs.
Installation
The latest version can be obtained from PyPI:
pip install flask-restful-hal
Usage
Flask-RESTful-HAL extends the Resource base class of Flask-RESTful. Instead of defining a get method, a static data method must be implemented which returns the contents of the resource class. In addition the two optional static methods embedded and links can be defined to describe which resources are embedded and linked to the current resource.
Example of a minimal resource class
from flask import Flask
from flask_restful_hal import Api, Resource
TODOS = {
'todo1': {
'task': 'build an API'
},
'todo2': {
'task': '?????'
},
'todo3': {
'task': 'profit!'
},
}
class Todo(Resource):
@staticmethod
def data(todo):
return TODOS[todo]
app = Flask(__name__)
api = Api(app)
api.add_resource(Todo, '/todos/<todo>')
app.run()
In this example, the only required method data is implemented and returns the requested todo entry as a Python dictionary. By default, this dictionary is parsed to a json string and returned in an HTTP response with content type application/hal+json. If the Python package json2html is installed, the client can request an HTML output as an alternative (by sending Accept: text/html).
When requesting the resource, the client may add the query string links=true to get linked resources. Since no links method is implemented, only the default self link will be included in the response.
Example of a resource class with embedded and linked resources
from flask import Flask, url_for
from flask_restful_hal import Api, Embedded, Link, Resource
TODOS = {
'todo1': {
'task': 'build an API'
},
'todo2': {
'task': '?????'
},
'todo3': {
'task': 'profit!'
},
}
class Todo(Resource):
@staticmethod
def data(todo):
return TODOS[todo]
@staticmethod
def links(todo):
return Link('collection', '/todos')
class TodoList(Resource):
@staticmethod
def data():
return {'size': len(TODOS)}
@staticmethod
def embedded():
arguments_list = [(todo, ) for todo in sorted(TODOS.keys())]
return Embedded('items', Todo, *arguments_list)
@staticmethod
def links():
arguments_list = [('/todos/{}'.format(todo), {'title': todo}) for todo in sorted(TODOS.keys())]
return Link('items', *arguments_list)
app = Flask(__name__)
api = Api(app)
api.add_resource(TodoList, '/todos')
api.add_resource(Todo, '/todos/<todo>')
app.run()
Links can be added by returning one or multiple Link objects from a static links routine. The Link constructor takes a relationship (e.g. collection, up or item) and one or multiple link targets. Link targets can either be expressed as a string (href attribute) or as a tuple consisting of a href string and a dictionary with extra attributes. In the example title is used as an extra attribute.
Embedded resources are expressed with one or multiple Embedded objects. Again, the first parameter is a relationship. The second parameter is the embedded resource class and the following parameters are tuples with constructor arguments for that class.
By default, no resources are embedded. Embedding resources can be requested with the query string embed=true which affects all resources recursively (embedded resources can embed resources as well). This behavior can be changed by specifying a concrete level of embedding (e.g. embed=2 would only embed two levels of resources).
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for flask_restful_hal-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 591a68b16f526f41f3a8443a684e6679a75308fa8dc6e67edd17d659346d3d2b |
|
MD5 | 0284806783caeaa193a37fc018572dc0 |
|
BLAKE2b-256 | 9b74baac3d2ef68735501a348cbec0a63b80b16983e700847e208fcf191b9d47 |
Hashes for flask_restful_hal-0.1.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a835070b958e4155b73708a53a3bbb440c778888acf0177918b72a36d0c89348 |
|
MD5 | aff94eecddb131ac1172284678351729 |
|
BLAKE2b-256 | 06b25d944b9fb648ccb1f61740a19ca1625564bdc2991961b1daa862ef2dde82 |