NetAPI

The NetAPI is an endpoint providing access to graphs. It provides the possibility to send queries and to receive responses with graphs.

Overview and Architecture

TODO:

Graph Sources

Implementations of Graph Sources provide events to create graphs. Typically a project requires a specific implementation which is responsible to create Events building a graph. This approach enables the use of project-specific data-structures and a normalized view of the contained graphs.

Queries, the QueryEngine and Responses

Queries are executed by an QueryEngine. The QueryEngine uses a model of different phases to create queried graphs. This model is depicted in the following image:

queryengine

Examples

TODO

NetAPI-Python

A Python3 client which enables creating and process queries via the NetAPI and to transform the responses to a graph. This can then be easily be used for further processes in Python3.

Installation

The netapi-python package has to be installed via pip - the package installer for Python. Two variants can be installed: a published stable version or the current development version. Normally, it is preferable to use the published stable version.

Virtual Environments

If you are working on several python projects each with a possible set of different dependencies it might be a good idea to create a virtual python environment for your project. E.g by issuing the following command:

python -m venv my-netapi-env

More info on this topic can be found here: https://docs.python.org/3/library/venv.html

Stable version

The current stable version can be installed via a pip-command:

python -m pip install netapi-python --extra-index-url https://gitea.plattform-gmbh.de/api/packages/PlattformGmbH/pypi/simple --user

If you already have a installed version of netapi-python in your local environment it can be updated using the following pip-command:

python -m pip install --upgrade --extra-index-url https://gitea.plattform-gmbh.de/api/packages/PlattformGmbH/pypi/simple netapi-python

Development version

The development version can be installed as a regular pip-module. The source code can be accessed via a git repository. If you have the necessary user authentication, it can be cloned like this:

git pull https://gitea.plattform-gmbh.de/PlattformGmbH/datacollector.git

After cloning the git repository the pip-module actually has to be installed:

cd datacollector/netapi-python
python -m pip install -e .

When changing / updating the source code it is automatically reflected in the pip-module. Thus a simple git pull often suffices to make sure that the newest development version is used.

Sometimes the dependencies of the NetAPI are updated. To make sure that also all dependencies are updated as well the install command from above has to be executed again.

Usage and examples

This section makes examples how to use the NetAPI-Python-Module.

Configuration

The NetAPI makes requests to another server. Often it is desireable that users should authenticate to the server to allow authorization to the requested resources.

Clients of the NetAPI can be configured via the file ~/.netapi/config (~ is the usual abbreviation of the current user’s home directory). An example of such a configuration file can be found below:

[default] (1)
host=https://qknow-dc.dev.plattform-gmbh.de (2)
token=atoken (3)

[qknow-live] (4)
host=https://qknow-dc.live.plattform-gmbh.de
token=anothertoken
1 A profile default is defined
2 The URL of the host where the NetAPI-Server resides
3 An authentication token.
4 A second profile qknow-live is defined

The profiles can be used the implemenations of the NetAPI to construct a suitable instance for the communication with the server. This will be demonstrated in the following source code examples.

The authentication is currently a simple version and will be changed in the near future as this version does not allow different users.

Read a graph

Demonstrates the most basic form of interaction with the NetAPI: reading a graph.

from netapi import * (1)

client = NetAPIClient.fromConfig("default") (2)

req = GraphQueryRequest()\
      .setSource("InputStreamReplayToSource", "MiniGraph.dgs") (3)
res = client.query(req) (4)

graphModel = res.getGraphModel() (5)
graph = graphModel.asMultiDiGraph() (6)

print(graph)
1 Imports the netapi-module
2 Creates a new instance of the NetAPICliente from the profile "default" using the configuration file.
3 Creates a request using the a InputStreamReplayToSource and a well-known file (actually a file for test-cases)
4 Sends the query and receives the response object
5 Extracts the generic graph model
6 Creates a networkx-view of the graph model. In this case a directed graph allowing for multiple edges between nodes.

Tagging

TODO

Aggregating nodes

TODO

Filter nodes and edges

TODO

QuestionService

Manuelle Tests des Servers (API-Tests)

  • Tools zum Stellen der Anfragen:

  • Ohne GUI: curl

  • Mit GUI: Postman. Siehe https://www.postman.com/

  • Übergabe der Nutzerinfo:

  • Nutzerinfos werden bei allen Anfragen im HEAD als Attribut "DC-User" übertragen. Wenn kein Nutzer angegeben ist, wird "guest" übertragen.

/questions?ctx.type=${contextType}&ctx.id=${contextId}]

Liefert die Menge der Fragen.

/contexts

Liefert die Menge der Kontexte.

/question?id=${questionId}

Liefert eine Frage mit der übergebenen ID.