Client architecture

This page explains how the illumio client is put together, so the rest of the library feels predictable rather than magical.

The registry: @pce_api

Every PCE resource is a dataclass decorated with @pce_api, which registers it in a global PCE_APIS mapping:

@dataclass
@pce_api('labels', endpoint='/labels')
class Label(MutableObject):
    ...

The decorator records the API name (labels), its endpoint, and two scoping flags — is_sec_policy and is_global (see Policy versioning & provisioning and Org scoping & global endpoints).

Dynamic dispatch: pce.<name>

PolicyComputeEngine has no hand-written labels attribute. Instead, PolicyComputeEngine.__getattr__ looks the name up in PCE_APIS and returns a _PCEObjectAPI instance bound to that resource:

pce.labels          # -> _PCEObjectAPI for the Label type
pce.labels.get()    # GET  /orgs/{org_id}/labels
pce.labels.create(Label(key='role', value='web'))

Because dispatch is data-driven, adding a resource is just adding a decorated dataclass — no changes to PolicyComputeEngine are required.

Generic CRUD: _PCEObjectAPI

_PCEObjectAPI provides the uniform CRUD surface every registered resource shares: get, get_by_reference, get_by_name, get_all, get_async, create, update, delete, and the bulk_* variants. It builds the request path from the resource’s endpoint and scoping flags, then encodes/decodes objects with the shared JSON machinery (see The object model).

Custom methods

Operations that go beyond CRUD — provisioning, VEN lifecycle actions, traffic queries, sub-resources like workload interfaces — are plain methods on PolicyComputeEngine. Reach for a custom method when a resource needs an action the generic CRUD interface doesn’t model.

See also

The object model for the dataclass hierarchy, and API Reference for the full reference.