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()
Related resources
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.