felix1m / sqlalchemy-jsonapi

JSONAPI implementation for use with SQLAlchemy

sqlalchemy-jsonapi

JSON API implementation for use with SQLAlchemy.

WARNING: JSON API is currently under active development. Thus the format of the API and this module may change drastically.

Installation

Just install the package via pip.

pip install sqlalchemy-jsonapi

Basic Usage

First, define your model using JSONAPIMixin.

from sqlalchemy_jsonapi import JSONAPIMixin, JSONAPI

class User(JSONAPIMixin, Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    # ...

Now, to serialize your model data, create a serializer object from JSONAPI:

user_serializer = JSONAPI(User)
collection = session.query(User).all()
print(user_serializer.serialize(collection))

Advanced Usage

To exclude columns or relationships, list them in the jsonapi_exclude_columns and jsonapi_exclude_relationships lists in your model:

class User(JSONAPIMixin, Base):
    __tablename__ = 'users'
    jsonapi_exclude_columns = ['password', 'social_security_number']
    jsonapi_exclude_relationships = ['credit_cards', 'php_test_fails']
    # ...

To include properties or generated relationships, use the jsonapi_extra_columns and jsonapi_extra_relationships lists:

from sqlalchemy_jsonapi import as_relationship

class User(JSONAPIMixin, Base):
    __tablename__ = 'users'
    jsonapi_extra_columns = ['lines_coded']
    jsonapi_extra_relationships = ['favorite_language']
    # ...

    @property
    def lines_coded(self):
        return self.lines.count()

    @as_relationship()
    def favorite_language(self):
        return self.languages.filter_by(is_favorite=True).first()

To override a property or relationship, you can simply exclude and then include. Or you can do a shortcut:

class User(JSONAPIMixin, Base):
    __tablename__ = 'users'
    jsonapi_column_data_overrides = {'id': lambda x: str(x.id)}
    jsonapi_override_relationships = {'is_admin': lambda x: x.roles.is_admin}

To add converters, simply subclass JSONAPI and use the converters property. Setting a type to None will prevent it from being serialized. For example:

class MySerializer(JSONAPI):
    converters = {'UUID': str,
                  'Password': None}

And finally, if you need your keys to be in a different format, override the inflector.

class MySerializer(JSONAPI):
    def inflector(self, to_inflect):
        return to_inflect.upper()