pyramid-jsonapi Documentation¶
pyramid-jsonapi aims to create a JSON-API (http://jsonapi.org/) standard API from a database using the sqlAlchemy ORM and pyramid framework.
Contents¶
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
The default branch of pyramid_jsonapi is now the 2.2 branch.
Documentation¶
Documentation is available at: https://colinhiggs.github.io/pyramid-jsonapi/
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 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
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().