Quickstart

Installation

Requirements

  • Python 3.10 or newer

  • Django 4.2+

  1. Install from PyPI using pip:

    pip install zgw-consumers

  2. Add zgw_consumers and simple_certmanager to the INSTALLED_APPS setting.

  3. Run python src/manage.py migrate to create the necessary database tables

  4. Configure django-simple-certmanager correctly

Note

If you want to support OAuth 2.0 authentication (client credentials flow), then install the library with the necessary extras:

(uv) pip install zgw-consumers[oauth2]

Usage

In the Django admin, you can create:

  • Service instances to define your external APIs.

  • NLXConfig configuration for your NLX outway.

Using ape-pie to interact with your service

From a service, you can construct an ape_pie.APIClient instance (which is nothing more than an extension to the requests.Session object).

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

my_service = Service.objects.get(api_root="https://api.example.com/")
client = build_client(my_service)

with client:
    # The preferred way to use the client is within a context manager
    client.get("relative/url")

The resulting client will have certificate and authentication automatically configured from the database configuration.

Note

By default, zgw_consumers.client.build_client() will return an instance of an zgw_consumers.nlx.NLXClient, which will take care of rewriting URLs. You can customize this behavior by using the client_factory argument.

If you want to customize how configuration is extracted from the zgw_consumers.models.Service, you can make use of the zgw_consumers.client.ServiceConfigAdapter directly.

Data model

Use zgw_consumers.api_models.base.factory to turn raw JSON responses into instances of domain models:

from zgw_consumers.api_models.base import factory
from zgw_consumers.api_models.zaken import Zaak

results = client.get("zaken")["results"]

return factory(Zaak, results)

It works for both collections and scalar values, and takes care of the camelCase to snake_case conversion.

You can also define your own data models, take a look at the zgw_consumers.api_models package for inspiration.