JSON-API responses in Python.
Hyp is a library implementing the must parts of the JSON-API response specification. This means that you can use Hyp to serialize your models into responses that contain links and linked compound documents. It works really good in combination with your micro web framework of choice, preferably Flask.
It has built in support for both Schematics and Marshmallow in the sense that you can use any of them for serializing your models (or primitives) into JSON that Hyp creates responses from. To add support for more data serialization libraries such as Colander should be trivial though.
First let's define some serializers for your models:
from marshmallow import Serializer, fields
class CommentSerializer(Serializer):
id = fields.Integer()
content = fields.String()
class PersonSerializer(Serializer):
id = fields.Integer()
name = fields.String()
class PostSerializer(Serializer):
id = fields.Integer()
title = fields.String()We can then create our own responders using the hyp.Responders class:
from hyp.responder import Responder
class CommentResponder(Responder):
TYPE = 'comment'
SERIALIZER = CommentSerializer
class PersonResponder(Responder):
TYPE = 'person'
SERIALIZER = PersonSerializer
class PostResponder(Responder):
TYPE = 'post'
SERIALIZER = PostSerializer
LINKS = {
'comments': {
'responder': CommentResponder(),
'href': 'http://example.com/comments/{posts.comments}',
},
'author': {
'responder': PersonResponder(),
'href': 'http://example.com/people/{posts.author}',
},
}Finally we can use our responders for creating responses. These responses goes perfectly into any Flask application out there:
post = {
'id': 1,
'title': 'My post',
'comments': [
{'id': 1, 'content': 'A comment'},
{'id': 2, 'content': 'Another comment'},
]
}
json = PostResponder.dumps(post, linked={'comments': post['comments']})The json variable will now contain some freshly squeezed JSON ready for sending back to the client:
{
"posts": [
{
"id": 1,
"title": "My title",
"links": {
"comments": [1, 2]
}
}
],
"linked": {
"comments": [
{
"id": 1,
"content": "My comment"
},
{
"id": 2,
"content": "Another comment"
}
]
},
"links": {
"posts.comments": {
"type": "comments",
"href": "http://example.com/comments/{posts.comments}"
}
}
}If you'd like to get have dict returned instead of json,
for example if you want to use flask's jsonify,
then you can use the build method instead like so:
post = {
'id': 1,
'title': 'My post',
'comments': [
{'id': 1, 'content': 'A comment'},
{'id': 2, 'content': 'Another comment'},
]
}
response = PostResponder.build(post, linked={'comments': post['comments']})
json = flask.jsonify(response)