Asynchronous JSON API
Project description
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 support the ?include
and ?fields
query parameters. All
GET
collection operations support the ?filter
and ?sort
query parameters
(by means of a preliminary implementation). All objects created and manipulated
through the web server are persisted in a Postgres database by ajsonapi.
Limitations
Note that ajsonapi is work in progress. The current version does not support the
remaining query parameter (?page
) yet.
Where to get it?
pip install ajsonapi
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.