Merge pull request #3519 from open-formulieren/refactor/3489-document…

…ation Document new API client & update configuration documentation
open-formulieren · Oct 10, 2023 · 04cb89e · 04cb89e
2 parents c4dadf7 + 629213f
commit 04cb89e
Show file tree

Hide file tree

Showing 33 changed files with 205 additions and 550 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -38,6 +38,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
+    "sphinx.ext.intersphinx",
     "sphinx_tabs.tabs",
     "recommonmark",
     # "sphinx_markdown_tables",
@@ -60,6 +61,21 @@
 
 source_suffix = [".rst", ".md"]
 
+intersphinx_mapping = {
+    "requests": (
+        "https://docs.python-requests.org/en/latest/",
+        None,
+    ),
+    "ape_pie": (
+        "https://ape-pie.readthedocs.io/en/latest/",
+        None,
+    ),
+    "django": (
+        "http://docs.djangoproject.com/en/3.2/",
+        "http://docs.djangoproject.com/en/3.2/_objects/",
+    ),
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

diff --git a/docs/configuration/prefill/bag.rst b/docs/configuration/prefill/bag.rst
@@ -25,15 +25,16 @@ Configuration
    * **Authorization type**: API key
    * **Header key**: X-Api-Key
    * **Header value**: *The BAG API key obtained in step 1*
-   * **OAS**: ``https://raw.githubusercontent.com/lvbag/BAG-API/4ab6ea5f3c2749f62d1079e2fe7539d4526c04e7/Technische%20specificatie/Archief/Yaml's/BAG%20API%20Individuele%20Bevragingen/resolved/individuelebevragingen/v2/adressen.yaml``
 
 4. Click **Save**
-5. Navigate to **Configuration** > **Overview**. In the **Address search plugin** group, click on **Configuration** for the **BAG** line.
+5. Navigate to **Configuration** > **Overview**. In the **Address lookup plugins**
+   group, click on **Configuration** for the **Kadaster API: BAG** line.
 6. Select for the **BAG service**, the **[ORC (Overige)] BAG (Kadaster)**
    option, that we just created in step 3.
 7. Click **Save**
 
-The BAG configuration is now completed.
+The BAG configuration is now complete. You can refresh the configuration overview page
+to do a connection check.
 
 .. _`BAG API`: https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/openapi.yaml
 .. _`BAG API key`: https://www.kadaster.nl/zakelijk/producten/adressen-en-gebouwen/bag-api-individuele-bevragingen

diff --git a/docs/configuration/prefill/haal_centraal.rst b/docs/configuration/prefill/haal_centraal.rst
@@ -36,15 +36,18 @@ Configuration
    * **Authorization type**: API key *(but can differ per supplier)*
    * **Header key**: Authorization
    * **Header value**: *The API key from step 1*
-   * **OAS**: *URL to the Open API-specification provided by supplier or use the Github raw URL*
 
 4. Click **Save**
-5. Navigate to **Configuration** > **Overview**. In the **Prefill plugin** group, click on **Configuration** for the **Haal Centraal** line.
-6. Select for the **Haal Centraal API**, the **[ORC (Overige)] My BRP API**
+5. Navigate to **Configuration** > **Configuration overview**. In the **Prefill plugins**
+   group, click on **Configuration** for the **Haal Centraal: BRP Personen Bevragen**
+   line.
+6. Select for the **BRP Personen Bevragen API**, the **[ORC (Overige)] My BRP API**
    option, that we just created in step 3.
-7. Click **Save**
+7. Select the correct version for **BRP Personen Bevragen API version** - new
+   installations likely use ``v2.0``.
+8. Click **Save**
 
-The Haal Centraal configuration is now completed.
+The Haal Centraal configuration is now complete.
 
 
 Technical
@@ -53,5 +56,6 @@ Technical
 ================  ===================
 API               Supported versions
 ================  ===================
-BRP bevragen API  1.0
+BRP bevragen API  2.0
+BRP bevragen API  1.3
 ================  ===================
diff --git a/docs/developers/backend/api-clients.rst b/docs/developers/backend/api-clients.rst
@@ -0,0 +1,80 @@
+.. _developers_backend_api_clients:
+
+===========
+API clients
+===========
+
+Background
+==========
+
+Open Forms interfaces over HTTP with a bunch of third party APIs/services, for example
+to:
+
+* fetch :ref:`prefill data <configuration_prefill_index>`
+* :ref:`register <configuration_registration_index>` submission data
+* perform :ref:`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 <https://ape-pie.readthedocs.io/en/latest/>`_.
+
+Because it extends the core :mod:`requests` API, usage should feel familiar.
+
+You are encouraged to define your own service-specific subclasses to modify behaviour
+where needed.
+
+.. _developers_backend_api_clients_factories:
+
+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 :class:`ape_pie.ConfigAdapter` protocol.
+
+Some examples that can serve as a reference:
+
+* :class:`zgw_consumers_ext.ape_pie.ServiceClientFactory`
+* :class:`soap.client.session_factory.SessionFactory`
+* :class:`stuf.service_client_factory.ServiceClientFactory`
+
+
+Reference
+=========
+
+ZGW-consumers (JSON-based/RESTful services)
+-------------------------------------------
+
+.. automodule:: zgw_consumers_ext.api_client
+    :members:
+
+Zeep (SOAP client)
+------------------
+
+Zeep supports a ``session`` keyword argument for its transport, which is plug and play
+with our base client.
+
+.. automodule:: soap.client
+    :members:
+
+StUF (template based SOAP/XML)
+------------------------------
+
+.. automodule:: stuf.client
+    :members:
diff --git a/docs/developers/backend/index.rst b/docs/developers/backend/index.rst
@@ -65,6 +65,7 @@ General purpose functionality
 .. toctree::
     :maxdepth: 1
 
+    api-clients
     core/utils
     core/tokens
     core/testing-tools

diff --git a/requirements/base.in b/requirements/base.in
@@ -1,4 +1,5 @@
 # Core python libraries
+ape-pie
 bleach[css] >= 5
 celery ~= 5.0
 celery-once

diff --git a/requirements/base.txt b/requirements/base.txt
@@ -8,6 +8,8 @@
 
 amqp==5.0.9
     # via kombu
+ape-pie==0.1.0
+    # via -r requirements/base.in
 asgiref==3.5.0
     # via django
 async-timeout==4.0.2
@@ -247,6 +249,7 @@ frozendict==2.3.4
 furl==2.1.2
     # via
     #   -r requirements/base.in
+    #   ape-pie
     #   django-digid-eherkenning
 gemma-zds-client==2.0.0
     # via zgw-consumers
@@ -401,6 +404,7 @@ redis==4.5.4
     #   portalocker
 requests==2.31.0
     # via
+    #   ape-pie
     #   django-camunda
     #   django-log-outgoing-requests
     #   gemma-zds-client

diff --git a/requirements/ci.txt b/requirements/ci.txt
@@ -13,6 +13,10 @@ amqp==5.0.9
     #   -c requirements/base.txt
     #   -r requirements/base.txt
     #   kombu
+ape-pie==0.1.0
+    # via
+    #   -c requirements/base.txt
+    #   -r requirements/base.txt
 asgiref==3.5.0
     # via
     #   -c requirements/base.txt
@@ -443,6 +447,7 @@ furl==2.1.2
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
+    #   ape-pie
     #   django-digid-eherkenning
 gemma-zds-client==2.0.0
     # via
@@ -775,6 +780,7 @@ requests==2.31.0
     # via
     #   -c requirements/base.txt
     #   -r requirements/base.txt
+    #   ape-pie
     #   django-camunda
     #   django-log-outgoing-requests
     #   gemma-zds-client

diff --git a/requirements/dev.txt b/requirements/dev.txt
@@ -16,6 +16,10 @@ amqp==5.0.9
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
     #   kombu
+ape-pie==0.1.0
+    # via
+    #   -c requirements/ci.txt
+    #   -r requirements/ci.txt
 asgiref==3.5.0
     # via
     #   -c requirements/ci.txt
@@ -494,6 +498,7 @@ furl==2.1.2
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
+    #   ape-pie
     #   django-digid-eherkenning
 gemma-zds-client==2.0.0
     # via
@@ -901,6 +906,7 @@ requests==2.31.0
     # via
     #   -c requirements/ci.txt
     #   -r requirements/ci.txt
+    #   ape-pie
     #   ddt-api-calls
     #   django-camunda
     #   django-log-outgoing-requests

diff --git a/requirements/extensions.txt b/requirements/extensions.txt
@@ -10,6 +10,10 @@ amqp==5.0.9
     # via
     #   -r requirements/base.txt
     #   kombu
+ape-pie==0.1.0
+    # via
+    #   -c requirements/base.in
+    #   -r requirements/base.txt
 asgiref==3.5.0
     # via
     #   -r requirements/base.txt
@@ -376,6 +380,7 @@ furl==2.1.2
     # via
     #   -c requirements/base.in
     #   -r requirements/base.txt
+    #   ape-pie
     #   django-digid-eherkenning
     #   open-forms-ext-token-exchange
 gemma-zds-client==2.0.0
@@ -625,6 +630,7 @@ redis==4.5.4
 requests==2.31.0
     # via
     #   -r requirements/base.txt
+    #   ape-pie
     #   django-camunda
     #   django-log-outgoing-requests
     #   gemma-zds-client

diff --git a/src/api_client/README.md b/src/api_client/README.md
diff --git a/src/api_client/__init__.py b/src/api_client/__init__.py