ltvolks / pyramid-jsonapi

Auto-build JSON API from sqlalchemy models using the pyramid framework

The pyramid-jsonapi project

Create a JSON-API (http://jsonapi.org/) standard API from a database using the sqlAlchemy ORM and pyramid framework.

The core idea behind pyramid-jsonapi is to create a working JSON-API automatically, starting from the sort of models.py file shipped with a typical pyramid + sqlalchemy application.

Note

Most work has shifted to an upcoming new version. The 2_2_master branch is where the development is happening, although the resulting release is likely to be named "3" rather than "2" due to the number of breaking changes. More information soon.

Documentation

Documentation is available at: https://colinhiggs.github.io/pyramid-jsonapi/

Quick start

Installing pyramid_jsonapi

pip install -i pyramid_jsonapi

See :ref:`getting-started` for other installation options, including installing development versions.

Auto-Creating an API

Declare your models somewhere using sqlalchemy's :func:`sqlalchemy.ext.declarative.declarative_base`. In this documentation we assume that you have done so in a file called models.py:

class Person(Base):
    __tablename__ = 'people'
    id = Column(BigInteger, primary_key=True, autoincrement=True)
    name = Column(Text)
    blogs = relationship('Blog', backref='owner')
    posts = relationship('Post', backref='author')

# and the rest...

If you are happy with the defaults, you can get away with the following additions to the standard pyramid alchemy scaffold's top level __init__.py:

import pyramid_jsonapi

from . import models # Your models module.


def main(global_config, **settings):

  # The usual stuff from the pyramid alchemy setup.
  config = Configurator(settings=settings)

  # pyramid_jsonapi uses the renderer labelled 'json'. As usual, if you have
  # any types to serialise that the default JSON renderer can't handle, you
  # must alter it. For example:
  #
  #renderer = JSON(sort_keys=True)
  #renderer.add_adapter(datetime.date, datetime_adapter)
  #config.add_renderer('json', renderer)

  # Instantiate a PyramidJSONAPI class instance.
  pj = pyramid_jsonapi.PyramidJSONAPI(config, models)

  # If you are using pyramid 1.7 or older, you will need to pass a third
  # argument to the constructor: a callable which accepts a CollectionView
  # instance as an argument and returns a sqlalchemy database session.
  #
  # For example:
  # pj = pyramid_jsonapi.PyramidJSONAPI(
  #   config, models, lambda view: models.DBSession
  # )

  # Create the routes and views automagically:
  pj.create_jsonapi_using_magic_and_pixie_dust()

  # Routes and views are added imperatively, so no need for a scan - unless
  # you have defined other routes and views declaratively.

  return config.make_wsgi_app()

Or, without all the comments:

import pyramid_jsonapi

from . import models


def main(global_config, **settings):
  config = Configurator(settings=settings)
  pj = pyramid_jsonapi.PyramidJSONAPI(config, models)
  pj.create_jsonapi_using_magic_and_pixie_dust()
  return config.make_wsgi_app()

Yes, there really is a method called :func:`pyramid_jsonapi.PyramidJSONAPI.create_jsonapi_using_magic_and_pixie_dust`. No, you don't have to call it that. If you are feeling more sensible you can use the synonym :func:`pyramid_jsonapi.PyramidJSONAPI.create_jsonapi`.