jsonapi-client 0.9.10

Client session

from jsonapi_client import Session, Filter, ResourceTuple

s = Session('http://localhost:8080/')
# To start session in async mode
s = Session('http://localhost:8080/', enable_async=True)

# You can also pass extra arguments that are passed directly to requests or aiohttp methods,
# such as authentication object
s = Session('http://localhost:8080/',
            request_kwargs=dict(auth=HTTPBasicAuth('user', 'password'))


# You can also use Session as a context manager. Changes are committed in the end
# and session is closed.
with Session(...) as s:
    your code

# Or with enable_async=True
async with Session(..., enable_async=True):
    your code

# If you are not using context manager, you need to close session manually
s.close()

# Again, don't forget to await in the AsyncIO mode
await s.close()

# Fetching documents
documents = s.get('resource_type')
# Or if you want only 1, then
documents = s.get('resource_type', 'id_of_document')

# AsyncIO the same but remember to await:
documents = await s.get('resource_type')

Filtering and including

# You need first to specify your filter instance.
# - filtering with two criteria (and)
filter = Filter(attribute='something', attribute2='something_else')
# - filtering some-dict.some-attr == 'something'
filter = Filter(some_dict__some_attr='something'))

# Same thing goes for including.
# - including two fields
include = Inclusion('related_field', 'other_related_field')

# Custom syntax for request parameters.
# If you have different URL schema for filtering or other GET parameters,
# you can implement your own Modifier class (derive it from Modifier and
# reimplement appended_query).
modifier = Modifier('filter[post]=1&filter[author]=2')

# All above classes subclass Modifier and can be added to concatenate
# parameters
modifier_sum = filter + include + modifier

# Now fetch your document
filtered = s.get('resource_type', modifier_sum) # AsyncIO with await

# To access resources included in document:
r1 = document.resources[0]  # first ResourceObject of document.
r2 = document.resource      # if there is only 1 resource we can use this

Pagination

# Pagination links can be accessed via Document object.
next_doc = document.links.next.fetch()
# AsyncIO
next_doc = await document.links.next.fetch()

# Iteration through results (uses pagination):
for r in s.iterate('resource_type'):
    print(r)

# AsyncIO:
async for r in s.iterate('resource_type'):
    print(r)

Resource attribute and relationship access

# - attribute access
attr1 = r1.some_attr
nested_attr = r1.some_dict.some_attr
#   Attributes can always also be accessed via __getitem__:
nested_attr = r1['some-dict']['some-attr']

# If there is namespace collision, you can also access attributes via .fields proxy
# (both attributes and relationships)
attr2 = r1.fields.some_attr

# - relationship access.
#   * Sync, this gives directly ResourceObject
rel = r1.some_relation
attr3 = r1.some_relation.some_attr  # Relationship attribute can be accessed directly

#   * AsyncIO, this gives Relationship object instead because we anyway need to
#     call asynchronous fetch function.
rel = r1.some_relation
#     To access ResourceObject you need to first fetch content
await r1.some_relation.fetch()
#     and then you can access associated resourceobject
res = r1.some_relation.resource
attr3 = res.some_attr  # Attribute access through ResourceObject

# If you need to access relatinoship object itself (with sync API), you can do it via
# .relationships proxy. For example, if you are interested in links or metadata
# provided within relationship, or intend to manipulate relationship.
rel_obj = r1.relationships.relation_name

Resource updating

# Updating / patching existing resources
r1.some_attr = 'something else'
# Patching element in nested json
r1.some_dict.some_dict.some_attr = 'something else'

# change relationships, to-many. Accepts also iterable of ResourceObjects/
# ResourceIdentifiers/ResourceTuples
r1.comments = ['1', '2']
# or if resource type is not known or can have multiple types of resources
r1.comments_or_people = [ResourceTuple('1', 'comments'), ResourceTuple('2', 'people')]
# or if you want to add some resources you can
r1.comments_or_people += [ResourceTuple('1', 'people')]
r1.commit()

# change to-one relationships
r1.author = '3'  # accepts also ResourceObjects/ResourceIdentifiers/ResourceTuple
# or resource type is not known (via schema etc.)
r1.author = ResourceTuple('3', 'people')

# Committing changes (PATCH request)
r1.commit(meta={'some_meta': 'data'})  # Resource committing supports optional meta data
# AsyncIO
await r1.commit(meta={'some_meta': 'data'})

Creating new resources

# Creating new resources. Schema must be given. Accepts dictionary of schema models
# (key is model name and value is schema as json-schema.org).

models_as_jsonschema = {
    'articles': {'properties': {
        'title': {'type': 'string'},
        'author': {'relation': 'to-one', 'resource': ['people']},
        'comments': {'relation': 'to-many', 'resource': ['comments']},
    }},
    'people': {'properties': {
        'first-name': {'type': 'string'},
        'last-name': {'type': 'string'},
        'twitter': {'type': ['null', 'string']},
    }},
    'comments': {'properties': {
        'body': {'type': 'string'},
     'author': {'relation': 'to-one', 'resource': ['people']}
 }}
}
# If you type schema by hand, it could be more convenient to type it as yml in a file
# instead

s = Session('http://localhost:8080/', schema=models_as_jsonschema)
a = s.create('articles') # Creates empty ResourceObject of 'articles' type
a.title = 'Test title'

# Validates and performs POST request, and finally updates resource based on server response
a.commit(meta={'some_meta': 'data'})
# Or with AsyncIO, remember to await
await a.commit(meta={'some_meta': 'data'})

# Commit metadata could be also saved in advance:
a.commit_metadata = {'some_meta': 'data'}
# You can also commit all changed resources in session by
s.commit()
# or with AsyncIO
await s.commit()

# Another example of resource creation, setting attributes and relationships & committing:
# If you have underscores in your field names, you can pass them in fields keyword argument as
# a dictionary:
cust1 = s.create_and_commit('articles',
                            attribute='1',
                            dict_object__attribute='2',
                            to_one_relationship='3',
                            to_many_relationship=['1', '2'],
                            fields={'some_field_with_underscore': '1'}
                            )

# Async:
cust1 = await s.create_and_commit('articles',
                                  attribute='1',
                                  dict_object__attribute='2',
                                  to_one_relationship='3',
                                  to_many_relationship=['1', '2'],
                                  fields={'some_field_with_underscore': '1'}
                                  )

Deleting resources

# Delete resource
cust1.delete() # Mark to be deleted
cust1.commit() # Actually delete

0.9.10 (2026-02-12)

• Fix async post custom header test for Python 3.8 compatible

• Replace dead batteries for Python 3.12

0.9.9 (2020-03-12)

• Adapt to aiohttp>3.0

• Workaround a weird bug

• Fix deprecation warnings

• Prevent AttributeDict() from modifying its input

• #24: Fix error handling of server response

0.9.8 (2020-02-14)

• #25: Fix for fetching resources without attributes

• Stop following next when there are no more items

• Fix build

• Use custom_url logic for all request methods

• #27: Await close on async sessions

• Add apk libffi-dev dependency

• Fix pytest.raise exception validation e.value

• Added .venv, .vscode, .pytest_cache to .gitignore

• Add support for extra headers as request_kwargs

0.9.7 (2019-02-01)

• Support __getitem__ in Meta

• Handle empty relationship data list

• Allow returning link to relationship as an iterator

• Fix handling null one-to-one-relationship

• Don’t explicitly quote filter values

• Include support

0.9.6 (2017-06-26)

• When creating new resources, use default value specified in jsonschema, when available.

0.9.5 (2017-06-16)

• Change Session.create_and_commit signature similarly as Session.create

0.9.4 (2017-06-16)

• Remove ? from filenames (illegal in Windows)

• Pass event loop aiohttp’s ClientSession

• Return resource from .commit if return status is 202

• Support underscores in field names in Session.create() through fields keyword argument.

• Add support for extra arguments such as authentication object

• AsyncIO support for context manager usage of Session

0.9.3 (2017-04-03)

• Added aiohttp to install requirements

0.9.2 (2017-04-03)

• Github release.

0.9.1 (2017-03-23)

• Fix async content_type checking

• Use Python 3’s new typing.NamedTuple instead of collections.NamedTuple

• Make included resources available from Document

• ResourceObject.json property