Recipes

In the recipes documentation, we aim to describe some patterns to organize your API calls to maximize performance.

If you can give the equivalent example in your own language-of-preference, please submit a pull request!

Creating a Zaak, a Document and relating them

Python (Django)Javascript

Using Django with zgw-consumers

import base64
from datetime import date
from requests import Response

from zgw_consumers.constants import APITypes
from zgw_consumers.models import Service
from zgw_consumers.client import build_client

zrc_client = build_client(Service.objects.get(api_type=APITypes.zrc))
drc_client = build_client(Service.objects.get(api_type=APITypes.drc))

# zaak creation
today = date.today().strftime("%Y-%m-%d")
zaak_body = {
    "zaaktype": "https://test.openzaak.nl/catalogi/api/v1/zaaktypen/4acb5ab8-f189-4559-b18a-8a54553a74ff",
    "bronorganisatie": "123456782",
    "verantwoordelijkeOrganisatie": "123456782",
    "registratiedatum": today,
    "startdatum": today,
}
zaak_response: Response = zrc_client.post("zaak", json=zaak_body)
zaak = zaak_response.json()

# document creation
with open("/tmp/some_file.txt", "rb") as some_file:
    document_body = {
        "bronorganisatie": "123456782",
        "creatiedatum": today,
        "titel": "Example document",
        "auteur": "Open Zaak",
        "inhoud": base64.b64encode(some_file.read()).decode("utf-8"),
        "bestandsomvang": some_file.size,
        "bestandsnaam": some_file.name,
        "taal": "nld",
        "informatieobjecttype": (
            "https://test.openzaak.nl/catalogi/api/v1/"
            "informatieobjecttypen/abb89dae-238e-4e6a-aacd-0ba9724350a9"
        )
    }
document_response: Response = drc_client.post("enkelvoudiginformatieobject", json=document_body)
document = document_response.json()

# relate them
zio_body = {
    "zaak": zaak["url"],
    "informatieobject": document["url"],
}
zio: Response = zrc_client.post("zaakinformatieobject", json=zio_body)

Retrieving the documents related to a Zaak

Key problem here is that one Zaak has (probably) multiple documents related to it, and retrieving them sequentially is a performance hit that gets worse with the amount of documents.

The solution is to use some form of threading/concurrency offered by your language.

Python (Django)Javascript

Using Django with zgw-consumers, we can use the concurrent.fututures.ThreadPoolExecutor, where each job will run in its own thread. This gets close to retrieving all the documents in parallel instead of sequentially, resulting in a constant-time determined by the slowest API call.

from typing import List

from zgw_consumers.constants import APITypes
from zgw_consumers.models import Service
from zgw_consumers.concurrent import parallel

zrc_client = Service.objects.filter(api_type=APITypes.zrc).get().build_client()
drc_client = Service.objects.filter(api_type=APITypes.drc).get().build_client()

zaak_url = "https://test.openzaak.nl/zaken/api/v1/zaken/b604ea56-f01c-432e-8d61-fd4ab02893dc"
zios: List[dict] = zrc_client.list("zaakinformatieobject", {"zaak": zaak_url})
document_urls = [zio["informatieobject"] for zio in zios]
with parallel() as executor:
    _documents = executor.map(
        lambda url: drc_client.retrieve("enkelvoudiginformatieobject", url=url),
        document_urls
    )
documents: List[dict] = list(_documents)