Skip to content

Latest commit

 

History

History
80 lines (54 loc) · 2.24 KB

api-clients.rst

File metadata and controls

80 lines (54 loc) · 2.24 KB
Raw

API clients

Background

Open Forms interfaces over HTTP with a bunch of third party APIs/services, for example to:

  • fetch prefill data <configuration_prefill_index>
  • register <configuration_registration_index> submission data
  • perform service fetch <example_service_fetch>

There are different flavours of interaction - JSON services (including REST), but also SOAP (XML), StUF (SOAP/XML-based standard) and unknowns that the future may bring.

In the Dutch (local) government landscape, there are some common patterns in how you connect with these services:

  • mutual TLS (mTLS)
  • basic auth credentials (username/password)
  • API key
  • Oauth2-based flows
  • IP allowlists

Combinations of these patterns are possible too!

Open Forms uses an abstraction that accounts for these variations while allowing developers to focus on the actual consuming of the service, packaged into the library ape-pie.

Because it extends the core requests API, usage should feel familiar.

You are encouraged to define your own service-specific subclasses to modify behaviour where needed.

Configuration factories

Configuration factories are a small abstraction that allow you to instantiate clients with the appropriate configuration/presets from sources holding the configuration details - for example database records.

Such a factory must implemented the ape_pie.ConfigAdapter protocol.

Some examples that can serve as a reference:

  • zgw_consumers_ext.ape_pie.ServiceClientFactory
  • soap.client.session_factory.SessionFactory
  • stuf.service_client_factory.ServiceClientFactory

Reference

ZGW-consumers (JSON-based/RESTful services)

zgw_consumers_ext.api_client

Zeep (SOAP client)

Zeep supports a session keyword argument for its transport, which is plug and play with our base client.

soap.client

StUF (template based SOAP/XML)

stuf.client