pyramid-jsonapi Documentation

pyramid-jsonapi aims to create a JSON-API ( standard API from a database using the sqlAlchemy ORM and pyramid framework.

The pyramid-jsonapi project

Create a JSON-API ( 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 file shipped with a typical pyramid + sqlalchemy application.


The default branch of pyramid_jsonapi is now the 2.2 branch.


Documentation is available at:

Quick start

Installing pyramid_jsonapi

pip install -i pyramid_jsonapi

See Getting Started for other installation options, including installing development versions.

Auto-Creating an API

Declare your models somewhere using sqlalchemy’s sqlalchemy.ext.declarative.declarative_base(). In this documentation we assume that you have done so in a file called

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

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_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:

  # 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)
  return config.make_wsgi_app()

Yes, there really is a method called 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 pyramid_jsonapi.PyramidJSONAPI.create_jsonapi().

Indices and tables