In the Common ground vision, data is retrieved from and mutated at the source. In practice, this means that a number of RESTful APIs are to be consumed to interact with the source.
This document provides an overview of available tooling for Python ecosystems.
The assumptions (and thus, requirements for the APIs) for this set of tooling are:
- APIs are RESTful
- APIs are documented in OpenAPI 3.0.x format, provided at
{api_root}/schema/openapi.yaml - APIs exchange data in JSON format with the
application/jsoncontent-type - APIs may be accessible only via NLX outways
gemma-zds-client is a client
library driven by the openapi.yaml schema provided by the API.
Currently, it does not intelligently transform schema type information into
native Python objects, i.e. every value is a string, float, integer, None or
any of the collection types (dict, list).
It does, however, provide a client class implementation suitable for working with NLX and handling URL rewrites. See also the NLX URL rewriter.
Status: stable.
NLX outways change the URLs of APIs - a path prefix of {organisation}/{service}
is added. You're also no longer accessing the canonical address, but your own,
local outway address which is often not understood by the service when using
URL-references.
nlx-url-rewriter is a Django package to handle this. You maintain the mapping of canonical address to outway address, and the rewriter modifies the data in place that you pass to it.
There is a pending issue for NLX to change to a transparent proxy, which will remove the need for URL-rewriting.
Status: beta.
zgw-consumers is another Django
package allowing you to store configuration. You can define a list of known
services and the required credentials (client_id and secret). It is aware
of the following API types:
- ZRC
- DRC
- ZTC
- BRC
- NRC
- AC
Extra API types can be supported easily. It provides an interface to build a client instance from a Service in the database.
Very useful if combined with a configuration tool where you can point to the primary service for a given domain, or for switching between NLX-enabled or non-NLX-enabled services.
Can easily work with NLX, since the config allows you to point to the NLX-enabled client class.
Status: stable.
django-camunda is a Django package allowing you to configure your Camunda process engine location, and interact with it.
It provides building blocks to start a camunda process via their REST API, has support for Celery for async tasks and an interface definition to handle custom variable types for Camunda processes.
Status: alpha.