ajsonapi

ajsonapi: asynchronous JSON API

What is it?

ajsonapi is a Python package for creating a JSON API web server backed by a database from a user-provided object model.

How to specify an object model?

Let's look at a simple object model specification.

# model.py

from ajsonapi import (JSON_API,
                      OneToManyRelationship,
                      ManyToOneRelationship,
                      Attribute,
                      String)

class Persons(JSON_API):
    name = Attribute(String)
    articles = OneToManyRelationship('Articles', rfkey='person_id')

class Articles(JSON_API):
    title = Attribute(String)
    author = ManyToOneRelationship('Persons', lfkey='person_id')

This model contains two class definitions: Persons and Articles. A person has a name and can author zero of more articles. An article has a title and has exactly one author (who is a person). The only parts in the model that may be unobvious are the lfkey and rfkey parameters in the relationship definitions. They are abbreviations for local foreign key and remote foreign key, respectively. Ajsonapi uses these parameters to identify that Persons.articles and Articles.author are each other's reverse relationship and to persist objects and their relationships in the database.

For a more elaborate (albeit abstract) object model see ajsonapi's model for functional testing.

How to create a web server?

# app.py

from aiohttp.web import run_app
from ajsonapi import Application

import model  # Or directly include the above code snippet

async def make_app():
    app = Application()
    await app.connect_database('postgresql://user:password@localhost:5432/db')
    await app.create_tables()
    app.add_json_api_routes()
    return app.app

run_app(make_app())

What does ajsonapi provide?

From the above six line model, ajsonapi creates a web server that supports the following eighteen operations (combinations of HTTP method and URI) as described by the JSON API specification.

GET, POST                 /persons
GET, PATCH, DELETE        /persons/{id}
GET, POST, PATCH, DELETE  /persons/{id}/relationships/articles
GET                       /persons/{id}/articles
GET, POST                 /articles
GET, PATCH, DELETE        /articles/{id}
GET, PATCH                /articles/{id}/relationships/author
GET                       /articles/{id}/author

All GET operations that return a collection support the ?include, ?fields, ?filter, ?sort, and ?page query parameters. All objects created and manipulated through the web server are persisted in a Postgres database by ajsonapi.

Where to get it?

pip install ajsonapi