JsonApi¶

The JsonApi allows you to insert records with an arbitrary JSON payload. The JSON payload will be encrypted and it will only be possible to decode the payload if you have the correct key. By default, the payload will be encrypted using the key used to insert the JSON payload, but it is possible to insert a JSON payload with different reading keys. To get an instance of the JsonApi, you can use the following example:

from pyil2 import IL2Client

client = IL2Client(
    host='https://il2.node:32032/',
    cert_filepath='rest.api.pfx',
    cert_password='Str0ngPassword'
)
api = client.api('json')

To insert a JSON encrypted with the certificate used to insert the JSON:

payload = {
    'attr': 'value'
}
json_doc = api.add_json_document(
    chain_id='UHtr...REDACTED...vXRY',
    payload=payload
)
serial = json_doc.serial

To get a JSON record and to decode the JSON payload:

json_doc = api.get_json_document(
    chain_id='UHtr...REDACTED...vXRY',
    serial=serial
)

decrypted = json_doc.encrypted_json.decode(client.certificate)

As stated earlier, you can store a JSON with a secondary reading key. The reading key needs to be in the IL2 format. Currently, the pyil2 client only supports PKCS12 certificates (PFX files), so you can use another PKCS12 certificate to add another reading key.

fom pyil2.utils.certificates import PKCS12Certificate

certificate_2 = PKCS12Certificate('certificate_2.pfx', 'Str0ngerPassword')

payload = {
    'attr': 'value'
}
json_doc = self.api.add_json_document_with_key(
    chain_id='UHtr...REDACTED...vXRY',
    payload=payload,
    public_key=certificate_2.pub_key,
    public_key_id=certificate_2.key_id
)

The decodification process is the same as before but using certificate_2 instead of client.certificate.

If you need multiples reading keys, you can insert a record with a list of allowed reading keys:

from pyil2.models.json import (
    AllowedReadersModel,
    ReaderKeyModel
)

allowed_readers = AllowedReadersModel(
    contextId='allowed_readers_list_name',
    readers=[
        ReaderKeyModel(
            name=certificate_2.key_id,
            public_key=certificate_2.pub_key
        )
    ]
)

reference = api.allow_json_document_readers(
    chain_id='UHtr...REDACTED...vXRY',
    allowed_readers=allowed_readers
)

With a list of allowed reading keys inserted, we can now insert a JSON document with more reading keys:

payload = {
    'attr': 'value'
}
json_doc = api.add_json_document_with_indirect_keys(
    chain_id='UHtr...REDACTED...vXRY',
    payload=payload,
    keys_references=[reference],
)

Note

You can use more than one allowed reading keys record reference.

Finally, you can also insert a JSON document record with all reading keys allowed in one chain:

payload = {
    'attr': 'value'
}
json_doc = api.add_json_document_with_chain_keys(
    chain_id='UHtr...REDACTED...vXRY',
    payload=payload,
    keys_chain_id=['ArFj...REDACTED...bHxP'],
)

The list of methods in the JsonApi are described as follows:

class pyil2.api.JsonApi(client: IL2Client)¶

Bases: BaseApi

API class for the JSON documents requests.

Parameters:: client (pyil2.IL2Client) – IL2Client to be used to send requests.

base_url¶

Base path of the requests.

Type:: str

add_json_document(chain_id: str, payload: Dict[str, Any]) → JsonDocumentModel | ErrorDetailsModel¶

Add a JSON document record encrypted with the client certificate used in the request.

Parameters:

chain_id (str) – Chain ID.
payload (dict) – A valid JSON in dictionary format.

Returns:

Added JSON document details.

Return type:

pyil2.models.json.JsonDocumentModel

add_json_document_with_chain_keys(chain_id: str, payload: Dict[str, Any], keys_chain_id: List[str]) → JsonDocumentModel | ErrorDetailsModel¶

Add a JSON document record encrypted with the public keys from a given list of chains.

Parameters:

chain_id (str) – Chain ID.
payload (dict) – A valid JSON in dictionary format.
keys_chain_id ([str]) – List of IDs of a local chain from which the ‘allowed readers’ list of public keys will be used to encrypt the content.

Returns:

Added JSON document details.

Return type:

pyil2.models.json.JsonDocumentModel

add_json_document_with_indirect_keys(chain_id: str, payload: Dict[str, Any], keys_references: List[str]) → JsonDocumentModel | ErrorDetailsModel¶

Add a JSON document record encrypted with the public keys from a given list of chains.

Parameters:

chain_id (str) – Chain ID.
payload (dict) – A valid JSON in dictionary format.
keys_references ([str]) – List of references on the format ‘chainId@serial’ to records on local chains containing ‘allowed readers’ lists.

Returns:

Added JSON document details.

Return type:

pyil2.models.json.JsonDocumentModel

add_json_document_with_key(chain_id: str, payload: Dict[str, Any], public_key: str, public_key_id: str) → JsonDocumentModel | ErrorDetailsModel¶

Add a JSON document record encrypted with a given key.

Parameters:

chain_id (str) – Chain ID.
payload (dict) – A valid JSON in dictionary format.
public_key (str) – IL2 text representation of a public key to encrypt the content for.
public_key_id (str) – IL2 text representation of the key ID.

Returns:

Added JSON document details.

Return type:

pyil2.models.json.JsonDocumentModel

allow_json_document_readers(chain_id: str, allowed_readers: AllowedReadersModel) → str | ErrorDetailsModel¶

Create a new list of allowed readers to encrypt JSON documents.

Parameters:

chain_id (str) – Chain ID.
allowed_readers (pyil2.models.json.AllowedReadersModel) – List of reader keys to be allowed.

Returns:

A record reference in the format chainId@recordSerial

Return type:

str

get_json_document(chain_id: str, serial: int) → JsonDocumentModel | ErrorDetailsModel¶

Get a JSON document record by serial number.

Parameters:

chain_id (str) – Chain ID.
serial (int) – Record serial number.

Returns:

JSON document details.

Return type:

pyil2.models.json.JsonDocumentModel

list_json_document_allowed_readers(chain_id: str, context_id: str = None, last_to_first: bool = False, page: int = 0, size: int = 10) → ListModel[AllowedReadersDetailsModel] | ErrorDetailsModel¶

Get a list of JSON document allowed reader keys.

Parameters:

chain_id (str) – Chain ID.
context_id (str) – Filter by context ID name.
last_to_first (bool) – If True, return the items in reverse order.
page (int) – Page to return.
size (int) – Number of items per page.

Returns:

List of allowed reader keys.

Return type:

pyil2.models.base.ListModel [pyil2.models.json.AllowedReadersDetailsModel]

JsonApi¶

IL2 Python Client

Navigation

Related Topics