Quickstart

Installation

Installation of SQLAlchemy-JSONAPI can be done via pip:

pip install -U sqlalchemy_jsonapi

Attaching to Declarative Base

To initialize the serializer, you first have to attach it to an instance of SQLAlchemy’s Declarative Base that is connected to your models:

from sqlalchemy_jsonapi import JSONAPI

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

class Address(Base):
    __tablename__ = 'address'
    id = Column(UUIDType, primary_key=True)
    user_id = Column(UUIDType, ForeignKey('users.id'))
    # ...

serializer = JSONAPI(Base)

Serialization

Now that your serializer is initialized, you can quickly and easily serialize your models. Let’s do a simple collection serialization:

@app.route('/api/users')
def users_list():
    response = serializer.get_collection(db.session, {}, 'users')
    return jsonify(response.data)

The third argument to get_collection where users is specified is the model type. This is auto-generated from the model name, but you can control this using __jsonapi_type_override__.

This is useful when you don’t want hyphenated type names. For example, a model named UserConfig will have a generated type of user-config. You can change this declaratively on the model:

class UserConfig(Base):
    __tablename__ = 'userconfig'
    __jsonapi_type_override__ = 'userconfig'

Deserialization

Deserialization is also quick and easy:

@app.route('/api/users/<user_id>', methods=['PATCH'])
def update_user(user_id):
    json_data = request.get_json(force=True)
    response = serializer.patch_resource(db.session, json_data, 'users', user_id)
    return jsonify(response.data)

If you use Flask, this can be automated and simplified via the included Flask module.