# jsonapi-client-framework
Json:API Client Framework provides an object-oriented approach to build your [Json:API](https://jsonapi.org/) clients.
## Installing
```sh
pip install jsonapi-client-framework
```
## Usage
```python
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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
from jsonapi_client import JsonAPIResourceIdentifier
class Movie(JsonAPIResourceSchema):
title: str
year: int
# By default, the Json:API payload contain the identifer only (id and type)
director: Person | JsonAPIResourceIdentifier
class Movies(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
```python
# GET https://your_api.domain.com/v1/people/49
person = people.resource("49").get()
```
### Update a resource
```python
# 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`](https://requests.readthedocs.io/en/latest/) library, so you can take advantage of
its [authentication](https://docs.python-requests.org/en/latest/user/authentication/) feature.
```python
from requests.auth import HTTPBasicAuth
people = People(base_url="https://your_api.domain.com/v1", auth=HTTPBasicAuth('user', 'pass'))
```
### Sub-collections
```python
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
```python
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
```python
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)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "jsonapi-client-framework",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "jsonapi",
"author": "Felipe Batista da Silva",
"author_email": "contact@batistadasilva.com",
"download_url": "https://files.pythonhosted.org/packages/ac/52/0f3cc11115c6600575fcfd838e2f28ba07c1d468de6083f2720b4257838a/jsonapi_client_framework-0.5.0.tar.gz",
"platform": null,
"description": "# jsonapi-client-framework\n\nJson:API Client Framework provides an object-oriented approach to build your [Json:API](https://jsonapi.org/) clients.\n\n## Installing\n\n```sh\npip install jsonapi-client-framework\n```\n\n## Usage\n\n```python\nfrom jsonapi_client import JsonAPICollection, JsonAPIResourceSchema\n\n\n# Create your dataclass\nclass Person(JsonAPIResourceSchema):\n first_name: str\n last_name: str\n year_of_birth: int\n\n\n# Easy setup\nclass People(JsonAPICollection[Person]):\n endpoint = \"/people\"\n schema = Person\n\n\npeople = People(base_url=\"https://your_api.domain.com/v1\")\n```\n\n## Features\n\n### Get full results as a list\n\n```python\n# GET https://your_api.domain.com/v1/people?page[number]=1\n# GET https://your_api.domain.com/v1/people?page[number]=2\n# ...\n# GET https://your_api.domain.com/v1/people?page[number]=23\npeople_list = people.list().all()\n```\n\n### Get a single result's page\n\n```python\n# GET https://your_api.domain.com/v1/people?page[number]=2\npeople_list, meta = people.list().paginated(page=2)\n\n# GET https://your_api.domain.com/v1/people?page[number]=2&page[size]=30\npeople_list, meta = people.list().paginated(page=2, size=30)\n```\n\n### Filter results\n\n```python\n# GET https://your_api.domain.com/v1/people?filter[date_of_birth]=1984&page=1\n# ...\n# GET https://your_api.domain.com/v1/people?filter[date_of_birth]=1984&page=4\npeople_list = people.list(filters={\"date_of_birth\": 1984}).all()\n```\n\n### Sort results\n\n```python\n# GET https://your_api.domain.com/v1/people?sort=first_name,last_name&page=1\n# ...\n# GET https://your_api.domain.com/v1/people?sort=first_name,last_name&page=23\npeople_list = people.list(sort=[\"first_name\", \"last_name\"]).all()\n```\n\n### Related resources\n\n```python\nfrom jsonapi_client import JsonAPIResourceIdentifier\n\n\nclass Movie(JsonAPIResourceSchema):\n title: str\n year: int\n # By default, the Json:API payload contain the identifer only (id and type)\n director: Person | JsonAPIResourceIdentifier\n\n\nclass Movies(JsonAPICollection[Movie]):\n endpoint = \"/movies\"\n schema = Movie\n\n\nmovies = Movies(base_url=\"https://your_api.domain.com/v1\")\n# GET https://your_api.domain.com/v1/movies/178\nmovie = movies.resource(\"178\").get()\nmovie.director.id # => \"7\"\n\nmovies_with_director = Movies(base_url=\"https://your_api.domain.com/v1\", include=\"diretor\")\n# GET https://your_api.domain.com/v1/movies/178?include=director\nmovie = movies_with_director.resource(\"178\").get()\nmovie.director.year_of_birth # => 1961\n\n# GET https://your_api.domain.com/v1/movies/178?include=director&page=1\n# ...\n# GET https://your_api.domain.com/v1/movies/178?include=director&page=117\nmovies_list = movies_with_director.list().all()\n```\n\n### Get a single resource as an object\n\n```python\n# GET https://your_api.domain.com/v1/people/49\nperson = people.resource(\"49\").get()\n```\n\n### Update a resource\n\n```python\n# PUT https://your_api.domain.com/v1/movies/179\n#\n# Request payload\n#\n# {\n# \"data\": {\n# \"attributes\": {\n# \"year\": 1993\n# },\n# \"relationships\": {\n# \"director\": {\n# \"data\": {\n# \"id\": \"55\"\n# }\n# }\n# }\n# }\n# }\nupdated_movies = movies.resource(\"179\").update(year=1993, director={\"id\": \"55\"})\n```\n\n## Advanced features\n\n### Authentication\n\nJson:API Client framework uses [`requests`](https://requests.readthedocs.io/en/latest/) library, so you can take advantage of\nits [authentication](https://docs.python-requests.org/en/latest/user/authentication/) feature.\n\n```python\nfrom requests.auth import HTTPBasicAuth\n\npeople = People(base_url=\"https://your_api.domain.com/v1\", auth=HTTPBasicAuth('user', 'pass'))\n```\n\n### Sub-collections\n\n```python\nfrom jsonapi_client import JsonAPIResourceSchema\n\n\nclass Movie(JsonAPIResourceSchema):\n title: str\n\n\nclass Theater(JsonAPIResourceSchema):\n name: str\n\n\nclass Theaters(JsonAPICollection[Theater]):\n endpoint = \"/theaters\"\n schema = Theater\n\n\nclass Movies(JsonAPICollection[Movie]):\n endpoint = \"/movies\"\n schema = Movie\n\n def theaters(self):\n return Theaters(base_url=f\"{self.base_url}{self.endpoint}\", auth=self.auth)\n\n\nmovies = Movies(base_url=\"https://your_api.domain.com/v1\", auth=HTTPBasicAuth('user', 'pass'))\n\n# GET https://your_api.domain.com/v1/movies/theaters?page=1\n# ...\n# GET https://your_api.domain.com/v1/movies/theaters&page=6\ntheaters_list = movies.theaters().list().all()\n```\n\n### Sub-resources\n\n```python\nfrom jsonapi_client import JsonAPIResourceSchema\nfrom jsonapi_client.resource import JsonAPIResource\n\n\nclass Movie(JsonAPIResourceSchema):\n title: str\n\n\nclass Character(JsonAPIResourceSchema):\n name: str\n\n\nclass Characters(JsonAPICollection[Character]):\n endpoint = \"/characters\"\n schema = Theater\n\n\nclass MovieResource(JsonAPIResource[Movie]):\n def characters(self):\n return Characters(base_url=self.url, auth=self.auth)\n\n\nclass Movies(JsonAPICollection[Movie]):\n endpoint = \"/movies\"\n schema = Movie\n\n\nmovies = Movies(base_url=\"https://your_api.domain.com/v1\", auth=HTTPBasicAuth('user', 'pass'))\n\n# GET https://your_api.domain.com/v1/movies/34/characters?page=1\n# ...\n# GET https://your_api.domain.com/v1/movies/34/characters?page=5\ncharacters_list = movies.resource(\"34\").characters().list().all()\n```\n\n### Custom encoding/decoding\n\n```python\nfrom datetime import datetime\n\nfrom jsonapi_client import encoders, decoders\n\ndef to_timestamp(datetime):\n return datetime.timestamp()\n\n# Encode/decode datetime objects as timestamps\nencoders.register(datetime, to_timestamp)\ndecoders.register(datetime, datetime.fromtimestamp)\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "An object-oriented framework for JSON:API clients.",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/hostnfly/jsonapi-client-framework",
"Issues": "https://github.com/hostnfly/jsonapi-client-framework/issues"
},
"split_keywords": [
"jsonapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "572620b37454a0f0172e875eb857fa9f636648873eb2992b04cb5b6aaa707368",
"md5": "2845995d9ecc8eeb5049e77ed1df2f7b",
"sha256": "8dddba0ae1e42b20808fe1a70f47f0b6235d3674f3f368e42276f5dbad7a76a0"
},
"downloads": -1,
"filename": "jsonapi_client_framework-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2845995d9ecc8eeb5049e77ed1df2f7b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10906,
"upload_time": "2025-01-08T09:29:22",
"upload_time_iso_8601": "2025-01-08T09:29:22.309619Z",
"url": "https://files.pythonhosted.org/packages/57/26/20b37454a0f0172e875eb857fa9f636648873eb2992b04cb5b6aaa707368/jsonapi_client_framework-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ac520f3cc11115c6600575fcfd838e2f28ba07c1d468de6083f2720b4257838a",
"md5": "ec353870f1b2133c77694cc640e9f54b",
"sha256": "e4894a3682c6f00b10dd94abdbd3ef33729abd940bd96a0bc480989ea9f2d787"
},
"downloads": -1,
"filename": "jsonapi_client_framework-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "ec353870f1b2133c77694cc640e9f54b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10179,
"upload_time": "2025-01-08T09:29:23",
"upload_time_iso_8601": "2025-01-08T09:29:23.454427Z",
"url": "https://files.pythonhosted.org/packages/ac/52/0f3cc11115c6600575fcfd838e2f28ba07c1d468de6083f2720b4257838a/jsonapi_client_framework-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-08 09:29:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hostnfly",
"github_project": "jsonapi-client-framework",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "jsonapi-client-framework"
}
JSON
