Partial JSON API implementation in Python
Python Makefile
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
hyp Raise NotImplemented error if ADAPTER not defined on Responder Oct 25, 2014
tests Raise NotImplemented error if ADAPTER not defined on Responder Oct 25, 2014
.gitignore
.travis.yml Add tox and travis support Oct 21, 2014
LICENSE Initial commit Feb 10, 2014
MANIFEST.in Split requirements and install requirements from package Feb 12, 2014
Makefile Run coverage reports on the correct package Apr 24, 2014
README.md Update README.md Dec 8, 2014
requirements-dev.txt Update dev requirements Oct 25, 2014
requirements.txt Remove hard dependencies that breaks on Python 3 Oct 22, 2014
setup.cfg Prepare for PyPI Feb 11, 2014
setup.py Use setuptools rather than distutils Oct 25, 2014
tox.ini Add tox and travis support Oct 21, 2014

README.md

Hyp Build Status

JSON-API responses in Python.

About

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.

Depending on which serialization library that you would like to use make sure to add it to your app's requirements.

Tutorial

First let's define some serializers for your models:

from marshmallow import Schema, fields


class CommentSchema(Schema):
    id = fields.Integer()
    content = fields.String()


class PersonSchema(Schema):
    id = fields.Integer()
    name = fields.String()


class PostSchema(Schema):
    id = fields.Integer()
    title = fields.String()

We can then create our own responders using the hyp.Responders class:

from hyp.marshmallow import Responder


class CommentResponder(Responder):
    TYPE = 'comments'
    SERIALIZER = CommentSchema


class PersonResponder(Responder):
    TYPE = 'people'
    SERIALIZER = PersonSchema


class PostResponder(Responder):
    TYPE = 'posts'
    SERIALIZER = PostSchema
    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.respond(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:

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)