Skip to main content

jsonapi-client-framework

Json:API Client Framework provides an object-oriented approach to build your Json:API clients.

Installing

pip install jsonapi-client-framework

Usage

from jsonapi_client import JsonAPICollection, JsonAPIResourceSchema


# Create your dataclass
class Person(JsonAPIResourceSchema):
    first_name: str
    last_name: str
    year_of_birth: int


# Easy setup
class People(JsonAPICollection[Person]):
    endpoint = "/people"
    schema = Person


people = People(base_url="https://your_api.domain.com/v1")

Features

Get full results as a list

# GET https://your_api.domain.com/v1/people?page[number]=1
# GET https://your_api.domain.com/v1/people?page[number]=2
# ...
# GET https://your_api.domain.com/v1/people?page[number]=23
people_list = people.list().all()

Get a single result's page

# GET https://your_api.domain.com/v1/people?page[number]=2
people_list, meta = people.list().paginated(page=2)

# GET https://your_api.domain.com/v1/people?page[number]=2&page[size]=30
people_list, meta = people.list().paginated(page=2, size=30)

Filter results

# GET https://your_api.domain.com/v1/people?filter[date_of_birth]=1984&page=1
# ...
# GET https://your_api.domain.com/v1/people?filter[date_of_birth]=1984&page=4
people_list = people.list(filters={"date_of_birth": 1984}).all()

Sort results

# GET https://your_api.domain.com/v1/people?sort=first_name,last_name&page=1
# ...
# GET https://your_api.domain.com/v1/people?sort=first_name,last_name&page=23
people_list = people.list(sort=["first_name", "last_name"]).all()
from jsonapi_client import JsonAPICollection, JsonAPIResourceIdentifier


@dataclass
class Movie(JsonAPIResourceSchema):
    title: str
    year: int
    # By default, the Json:API payload contain the identifer only (id and type)
    director: Person | JsonAPIResourceIdentifier


class JsonAPIMovies(JsonAPICollection[Movie]):
    endpoint = "/movies"
    schema = Movie


movies = Movies(base_url="https://your_api.domain.com/v1")
# GET https://your_api.domain.com/v1/movies/178
movie = movies.resource("178").get()
movie.director.id  # => "7"

movies_with_director = Movies(base_url="https://your_api.domain.com/v1", include="diretor")
# GET https://your_api.domain.com/v1/movies/178?include=director
movie = movies_with_director.resource("178").get()
movie.director.year_of_birth  # => 1961

# GET https://your_api.domain.com/v1/movies/178?include=director&page=1
# ...
# GET https://your_api.domain.com/v1/movies/178?include=director&page=117
movies_list = movies_with_director.list().all()

Get a single resource as an object

# GET https://your_api.domain.com/v1/people/49
person = people.resource("49").get()

Update a resource

# PUT https://your_api.domain.com/v1/movies/179
#
# Request payload
#
# {
#   "data": {
#     "attributes": {
#       "year": 1993
#     },
#     "relationships": {
#       "director": {
#         "data": {
#           "id": "55"
#         }
#       }
#     }
#   }
# }
updated_movies = movies.resource("179").update(year=1993, director={"id": "55"})

Advanced features

Authentication

Json:API Client framework uses requests library, so you can take advantage of its authentication feature.

from requests.auth import HTTPBasicAuth

people = People(base_url="https://your_api.domain.com/v1", auth=HTTPBasicAuth('user', 'pass'))

Sub-collections

from jsonapi_client import JsonAPIResourceSchema


class Movie(JsonAPIResourceSchema):
    title: str


class Theater(JsonAPIResourceSchema):
    name: str


class Theaters(JsonAPICollection[Theater]):
    endpoint = "/theaters"
    schema = Theater


class Movies(JsonAPICollection[Movie]):
    endpoint = "/movies"
    schema = Movie

    def theaters(self):
        return Theaters(base_url=f"{self.base_url}{self.endpoint}", auth=self.auth)


movies = Movies(base_url="https://your_api.domain.com/v1", auth=HTTPBasicAuth('user', 'pass'))

# GET https://your_api.domain.com/v1/movies/theaters?page=1
# ...
# GET https://your_api.domain.com/v1/movies/theaters&page=6
theaters_list = movies.theaters().list().all()

Sub-resources

from jsonapi_client import JsonAPIResourceSchema
from jsonapi_client.resource import JsonAPIResource


class Movie(JsonAPIResourceSchema):
    title: str


class Character(JsonAPIResourceSchema):
    name: str


class Characters(JsonAPICollection[Character]):
    endpoint = "/characters"
    schema = Theater


class MovieResource(JsonAPIResource[Movie]):
    def characters(self):
        return Characters(base_url=self.url, auth=self.auth)


class Movies(JsonAPICollection[Movie]):
    endpoint = "/movies"
    schema = Movie


movies = Movies(base_url="https://your_api.domain.com/v1", auth=HTTPBasicAuth('user', 'pass'))

# GET https://your_api.domain.com/v1/movies/34/characters?page=1
# ...
# GET https://your_api.domain.com/v1/movies/34/characters?page=5
characters_list = movies.resource("34").characters().list().all()

Custom encoding/decoding

from datetime import datetime

from jsonapi_client import encoders, decoders

def to_timestamp(datetime):
    return datetime.timestamp()

# Encode/decode datetime objects as timestamps
encoders.register(datetime, to_timestamp)
decoders.register(datetime, datetime.fromtimestamp)

Metadata

Release files for jsonapi-client-framework 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jsonapi-client-framework 1.1.0
File Size Uploaded Provenance Actions
jsonapi_client_framework-1.1.0.tar.gz 11.5 kB Without provenance Details for jsonapi_client_framework-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jsonapi-client-framework 1.1.0
File Interpreter ABI Platform Actions
jsonapi_client_framework-1.1.0-py3-none-any.whl Python 3 none any Details for jsonapi_client_framework-1.1.0-py3-none-any.whl

Total release size: 22.7 kB

Release files / jsonapi_client_framework-1.1.0.tar.gz

Download URL jsonapi_client_framework-1.1.0.tar.gz
Size 11.5 kB
Tags Source
SHA-256 checksum
How to use checksums
d3b207237d4dcefe78ea99bbea9e7143aea24b6d4c2ab4c588ca99e6d3737ed7
BLAKE2b-256 checksum
How to use checksums
a72dbfe372f52019244098457ac1e5bf4890e6965c8fc67096a9d1125303117e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.15

Release files / jsonapi_client_framework-1.1.0-py3-none-any.whl

Download URL jsonapi_client_framework-1.1.0-py3-none-any.whl
Size 11.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7da1063915a1c28dc8c78be11e91f0b0b7551b3aa1b33784bedc6a8feb11a270
BLAKE2b-256 checksum
How to use checksums
dbcd1f5dab84e4022c9be91269b4bd92ba2a07375d3d45144339f132803b7d9f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.15

Security for jsonapi-client-framework 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page