OpaqueApi

The OpaqueApi allows you to insert records with an opaque payload to an IL2 chain. The opaque payload allows you to insert any kind of data in raw bytes. This way you can insert an arbitrary object using your own data format. To get an instance of the OpaqueApi, 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('opaque')

Although each application in IL2 has its own identification by an integer number. The opaque record allows you to use any application ID. If your application requires different types of payload, you can use different codes for each type by using the payload_type_id to identify the different payloads. In summary, the opaque record allows you to use IL2 as your application need. To insert an opaque record, you can use the following method:

opaque = api.add_opaque(
    chain_id='UHtr...REDACTED...vXRY',
    application_id=123,
    payload_type_id=1234,
    payload=b'mydata'
)

To retrieve an opaque record you just use the following:

opaque = api.get_opaque(
    chain_id='UHtr...REDACTED...vXRY',
    serial=42
)
# my_custom_deserializer is your function to deserialize the payload
my_object = my_custom_deserializer(opaque.payload)

The list of methods are described as follows:

class pyil2.api.OpaqueApi(client: IL2Client)

Bases: BaseApi

API class for the opaque requests.

Parameters:

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

base_url

Base path of the requests.

Type:

str

add_opaque(chain_id: str, application_id: int, payload_type_id: int, payload: bytes, last_changed_serial: int = None) → OpaqueRecordModel | ErrorDetailsModel

Add an opaque record in a chain.

If the last_changed_serial is passed, it will fail to add the opaque record if the last record serial in the chain is not equal to the value passed. If None is passed, no verification is made.

Parameters:

  • chain_id (str) – Chain ID.

  • application_id (int) – Application ID for the block.

  • payload_type_id (int) – The payload’s Type ID.

  • payload (bytes) – Payload bytes.

  • last_changed_serial (int) – The serial number that the last record in the chain must be equal.

Returns:

Opaque record details.

Return type:

pyil2.models.record.OpaqueRecordModel

get_opaque(chain_id: str, serial: int) → OpaqueRecordModel | ErrorDetailsModel

Get an opaque record in a chain by serial number.

Parameters:

  • chain_id (str) – Chain ID.

  • serial (int) – Record serial number.

Returns:

Opaque record details.

Return type:

pyil2.models.record.OpaqueRecordModel

query_opaque(chain_id: str, application_id: int, payload_type_ids: List[int] = None, how_many: int = None, last_to_first: bool = False, page: int = 0, size: int = 10) → ListModel[OpaqueRecordModel] | ErrorDetailsModel

Query opaque records in a chain.

Parameters:

  • chain_id (str) – Chain ID.

  • application_id (int) – Application ID which records will be queried.

  • payload_type_ids ([int]) – List of opaque payload type IDs.

  • how_many (int) – How many records to return. If ommited or 0 returns all.

  • 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 opaque records in a chain.

Return type:

pyil2.models.base.ListModel [pyil2.models.record.OpaqueRecordModel]