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.
Just install the package via pip.
pip install sqlalchemy-jsonapi
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))
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()