API Reference

Models

jsonapi.model.MIME_TYPE = 'application/vnd.api+json'

The mime type to be used as the value of the Content-Type header

jsonapi.model.SEARCH_PAGE_SIZE = 50

The default value for the “page[size]” option when searching

class jsonapi.model.Model

A model defines a JSON API resource.

type_

Unique resource type (str)

See Defining Models for more details.

from_

A variable length list of tables, table aliases, or jsonapi.db.FromItem s.

See Defining Models for more details.

fields

A sequence of fields or field names.

See Defining Models for more details.

access

An SQL function providing object-level access protection.

See Protecting Models for more details.

user

A thread-safe object representing a logged-in user.

See Protecting Models for more details.

search

A full-text index table.

See Searching for more details.

get_object(args, object_id)

Fetch a resource object.

>>> from jsonapi.tests.model import UserModel
>>> await UserModel().get_object({}, 1)
{
    'data': {
        'id': '1',
        'type': 'user',
        'attributes': {
            'email': 'dianagraham@fisher.com',
            'first': 'Robert',
            'last': 'Camacho'
        }
    }
}
>>> await UserModel().get_object({}, email='dianagraham@fisher.com')
>>> await UserModel().get_object({}, first='Robert', last: 'Camacho'})

Parameters:

• args (dict) – a dictionary representing the request query string
• object_id (int|str) – the resource object id

Returns:

JSON API response document

See Fetching Data: Single Object for more details.

get_collection(args, search=None)

Fetch a collection of resources.

>>> from jsonapi.tests.model import UserModel
>>> await UserModel().get_collection({})
{'data':
    [
        {'id': '1',
         'type': 'user',
         'attributes': {
             'email': 'dianagraham@fisher.com',
             'first': 'Robert',
             'last': 'Camacho',
             'createdOn': '2019-05-18T11:49:43Z',
             'status': 'active',
             'name': 'Robert Camacho'}
         },
        ...
    ]
}

Parameters:

• args (dict) – a dictionary representing the request query string
• search (str) – an optional search term

Returns:

JSON API response document

See Fetching Data: Collections for more details.

get_related(args, object_id, relationship_name, search=None)

Fetch a collection of related resources.

>>> from jsonapi.tests.model import ArticleModel
>>> await ArticleModel().get_related({
>>>     'include': 'articles.comments,articles.keywords',
>>>     'fields[article]': 'title,body',
>>>     'fields[comments]': 'body'
>>> }, 1, 'author')

Parameters:

• args (dict) – a dictionary representing the request query string
• object_id (int|str) – the resource object id
• relationship_name (str) – relationship name
• search (str) – an optional search term

Returns:

JSON API response document

See Fetching Data: Related Objects for more details.

jsonapi.model.search(args, term, *models)

Search multiple models.

Returns a heterogeneous list of objects, sorted by search result rank.

>>> from jsonapi.model import search
>>> search({'include[user]': 'bio',
>>>         'include[article]': 'keywords,author.bio,publisher.bio',
>>>         'fields[user]': 'name,email',
>>>         'fields[user-bio]': 'birthday,age',
>>>         'fields[article]': 'title'},
>>>         'John', UserModel, ArticleModel)

Parameters:

• args (dict) – a dictionary representing the request query string
• term (str) – a PostgreSQL full text search query string (e.x. 'foo:* & !bar')
• models (Model) – variable length list of model classes or instances

Returns:

JSON API response document

See Searching for more details.

From Items

class jsonapi.db.table.FromItem(table, **kwargs)

Represent a single item in the FROM list of a SELECT query.

Each FromItem item represents a table (or an alias to a table). A FromItem object may include an onclause used when joining with other FromItem objects. If the left flag is set, an outer left join is performed.

>>> from jsonapi.tests.db import users_t, user_names_t
>>> a = FromItem(user_names_t)
>>> b = FromItem(user_names_t, users_t.c.id == user_names_t.c.id)
>>> c = FromItem(user_names_t, users_t.c.id == user_names_t.c.id, left=True)
>>> d = FromItem(user_names_t, left=True)
>>> b
<FromItem(user_names)>
>>> b.onclause
<sqlalchemy.sql.elements.BinaryExpression object at ...>
>>> b.left
False
>>> b.name
user_names
>>> print(b)
user_names

__init__(table, **kwargs)

Parameters:

• table – an SQLAlchemy Table or Alias object
• onclause – an onclause join expression (optional)
• left – if set perform outer left join (optional)

Fields

Basic Fields

class jsonapi.fields.Field(name, col=None, data_type=None)

Basic field type, which maps to a database table column or a column expression.

>>> from jsonapi.datatypes import Date
>>> from jsonapi.tests.db import users_t
>>>
>>> Field('email')
>>> Field('email-address', users_t.c.email)
>>> Field('name', lambda c: c.first + ' ' + c.last)
>>> Field('created-on', data_type=Date)

__init__(name, col=None, data_type=None)

Parameters:

• name (str) – a unique field name
• func (lambda) – a lambda function that accepts a ColumnCollection (optional)
• data_type (DataType) – defaults to String (optional)

Aggregate Fields

class jsonapi.fields.Aggregate(name, expr, func, field_type=Integer)

Aggregate.__init__(name, expr, func, field_type=Integer)

Parameters:

• name (str) – field name
• rel_name – relationship name
• func – SQLAlchemy aggregate function (ex. func.count)
• data_type (DataType) – one of the supported data types (optional)

Relationships

class jsonapi.fields.Relationship(name, model_name, cardinality, *refs, **kwargs)

Represents a relationship field.

>>> from jsonapi.model import ONE_TO_MANY
>>> from jsonapi.tests.db import articles_t
>>>
>>> Relationship('articles', 'ArticleModel', ONE_TO_MANY,
>>>              articles_t.c.author_id)

__init__(name, model_name, cardinality, *refs, **kwargs)

Parameters:

• name (str) – relationship name
• model_name (str) – related model name
• cardinality (Cardinality) – relationship cardinality
• refs – a variable length list of foreign key columns

Cardinality

class jsonapi.db.table.Cardinality

The cardinality of a relationship between two models.

• ONE_TO_ONE
• MANY_TO_ONE
• ONE_TO_MANY
• MANY_TO_MANY