Metadata-Version: 2.1
Name: gemma-zds-client
Version: 0.13.4
Summary: Generieke client voor GEMMA-zaken componenten
Home-page: https://github.com/VNG-Realisatie/gemma-zds-client
Author: Maykin Media, VNG-Realisatie
Author-email: support@maykinmedia.nl
License: EUPL 1.2
Keywords: openapi,swagger,django,vng,client,requests
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: pyjwt
Requires-Dist: pyyaml
Requires-Dist: requests
Provides-Extra: coverage
Requires-Dist: pytest-cov ; extra == 'coverage'
Provides-Extra: docs
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
Provides-Extra: nlx
Requires-Dist: nlx-url-rewriter ; extra == 'nlx'
Provides-Extra: pep8
Requires-Dist: flake8 ; extra == 'pep8'
Provides-Extra: release
Requires-Dist: zest.releaser ; extra == 'release'
Provides-Extra: tests
Requires-Dist: pytest ; extra == 'tests'
Requires-Dist: tox ; extra == 'tests'
Requires-Dist: isort ; extra == 'tests'
Requires-Dist: requests-mock ; extra == 'tests'

==========================================================
ZDS-Client - Generieke client voor GEMMA-zaken componenten
==========================================================

|build-status|

De ZDS-Client is een (voorlopig) interne client die op basis van OAS 3.0
specificaties met GEMMA-zaken componenten communiceert.

.. contents::

.. section-numbering::

Features
========

* Ophalen van OAS 3.0 spec & caching
* Aanmaken van resources volgens specificatie
* Generieke opzet, maar specifiek gebruik in de zaakgericht-werken services
* Introspectie in het OAS schema: lees op basis van een resource URL uit wat
  er precies hoort achter deze URL te zitten.
* ZDS autorisatiemodel via JWT out-of-the-box ondersteund.

Installatie
===========

Benodigdheden
-------------

* Python 3.6 of hoger
* setuptools 30.3.0 of hoger

Installeren
-----------

.. code-block:: bash

    pip install gemma-zds-client

Gebruik
=======

Initialiseren (statische configuratie)
--------------------------------------

De client moet geinitialiseerd worden met de locatie van de componenten. Dit
kan eenmalig of just-in-time wanneer je de client nodig hebt:

.. code-block:: bash

    from zds_client import Client

    Client.load_config('/pad/naar/config.yml')


De makkelijkste manier is configuratie via een ``yaml`` bestand, in het formaat:

.. code-block:: yaml

    ---

    zrc:
      scheme: http
      host: localhost
      port: 8000
      auth:
        client_id: my-zrc-client-id
        secret: my-zrc-client-secret
        scopes:
          - zds.scopes.zaken.aanmaken

    drc:
      scheme: http
      host: localhost
      port: 8001

    ztc:
      scheme: http
      host: localhost
      port: 8002

    orc:
      scheme: http
      host: localhost
      port: 8003


De key is de naam van de component.

Je kan echter ook de configuratie zonder yaml bestand doen, en volledig
gebruik maken van Python dictonaries, bijvoorbeeld:

.. code-block:: python

    from zds_client import Client

    ZRC = {
        'scheme': 'http',
        'host': 'localhost',
        'port': 8000,
    }

    DRC = {
        'scheme': 'http',
        'host': 'localhost',
        'port': 8001,
    }

    Client.load_config(**{
        'zrc': ZRC,
        'drc': DRC,
        ...
    })

Initialiseren (ad-hoc configuratie)
-----------------------------------

Je kan ook een client instance verkrijgen op basis van een specifieke resource
URL.

.. code-block:: python

    from zds_client import Client

    client = Client.from_url('https://api.nl/v1/resource/123')

Indien authorisatie hierop nodig is, kan je deze zelf assignen:

.. code-block:: python

    from zds_client import ClientAuth

    client.auth = ClientAuth(
        client_id='my-client-id',
        secret='my-client-secret',
        **claims
    )

Resources manipuleren
---------------------

Per component kan je vervolgens een client resources laten opvragen of
manipuleren:

.. code-block:: python

    zrc_client = Client('zrc')  # gebruik alias uit configuratie

    # oplijsten
    zaken = zrc_client.list('zaak')

    # opvragen
    zaak = zrc_client.retrieve('zaak', uuid='<uuid>')

    # opvragen met URL
    zaak = zrc_client.retrieve('zaak', url='<zaak_url>')

    # aanmaken
    zaak = zrc_client.create('zaak', {
        'bronorganisatie': '000000000',
        'zaaktype': 'http://localhost:8002/api/v1/zaaktypen/<uuid>'
    })


Schema introspectie
-------------------

Met de ``schema`` module kan je introspectie doen op resource URLs:

.. code-block:: python

    from zds_client import Client
    from zds_client.schema import Schema

    zrc_client = Client('zrc')  # gebruik alias uit configuratie

    schema = Schema(zrc_client.schema)

    input_schema = schema.get_request_resource_schema(
        'https://api.nl/v1/resource/123', method='GET'
    )
    assert input_schema['type'] == 'object'

    params = schema.get_request_parameters(
        'https://api.nl/v1/resource/123', method='GET'
    )
    assert type(params) == list

    output_schema = schema.get_response_resource_schema(
        'https://api.nl/v1/resource/123',
        method='GET', status_code='200'
    )
    assert output_schema['type'] == 'object'

Usage with NLX
--------------

When you're using NLX outways, the URLs of resources change because of this.
Services expoxed via NLX inways don't understand local outway URLs, so these
need to get rewritten.

In Django projects, you can make use of `nlx-url-rewriter`_ to define rewrite
targets before the requests are sent and right after responses are received.

The rewriter is implemented in the ``zds_client.nlx.NLXClient`` class, which
you can use instead of ``zds_client.Client``.

Install using:

.. code-block:: bash

    pip install gemma-zds-client[nlx]

This will pull in the extra dependencies. Make sure to follow the `nlx-url-rewriter`_
setup instructions.


.. |build-status| image:: https://travis-ci.org/VNG-Realisatie/gemma-zds-client.svg?branch=master
    :alt: Build status
    :target: https://travis-ci.org/VNG-Realisatie/gemma-zds-client

.. _nlx-url-rewriter: https://pypi.org/project/nlx-url-rewriter/


