API II

Was ist ein API?

Eine API (Application Programming Interface) ist eine Schnittstelle, über die verschiedene Softwareanwendungen miteinander kommunizieren können. Ein API legt Regeln fest, wie die Informationen zwischen den Programmen ausgetauscht werden.

Mit den API II ist es also möglich, mit selbst programmierter Software auf die Funktionen von RFEM 6 / RSTAB 9 zuzugreifen. So ist es beispielsweise möglich, Modelle zu generieren, Lasten zu erzeugen, die Berechnung zu starten und schließlich können die Ergebnisse ausgelesen werden.

In RFEM 6 / RSTAB 9 gibt es bereits ein API, die Webservice-Schnittstelle (API I). Diese bleibt auch weiterhin erhalten. Es ist also nicht zwingend notwendig, bereits erstellte Software auf das API II umzustellen.

Wenn in RFEM 6 / RSTAB 9 neue Funktionalitäten hinzugefügt werden, dann werden diese nur im API II verfügbar. Der API I bleibt auf den jetzigen Stand "eingefroren".

Was sind die technischen Unterschiede zum "alten" API?

Zunächst erst einmal basieren beide Schnittstellen auf der Webservice-Technologie. RFEM 6 / RSTAB 9 kommuniziert also mit der Client-Software über das HTTP-Protokoll (bzw. HTTPS-Protokoll).

Beim API I tauschen Client und Server Nachrichten im SOAP-Format aus. Im Gegensatz dazu verwendet API II statt dessen das gRPC-Protokoll.

Mit SOAP werden Nachrichten im XML-Format ausgetauscht. Die Kommunikation mittels SOAP hat relativ viel Overhead.

Im Gegensatz dazu werden bei gRPC die Nachrichten in einem leichtgewichtigen protokollbuffer-basierten Binärformat ausgetauscht. Das ist wesentlich effizienter als textbasierte Formate wie XML oder JSON.

Bei gRPC wird das neuere HTTP/2-Protokoll verwendet, was die Übertragung ebenfalls effizienter macht.

Im neuen API II ist es möglich, dass mehrere Objekte in einer Liste zusammengefasst werden können und dann übergeben werden. Es sind also nicht mehr viele kleine API-Aufrufe nötig, sondern nur noch wenige. Dadurch steigt ebenfalls die Effizienz. Im Beispiel unten wird demonstriert, wie diese Batch-Technik funktioniert.

All diese Maßnahmen zu Effizienzsteigerung führen dazu, dass die Kommunikation über das neue API II ca. um den Faktor 10 schneller als über API I ist.

Das API II ermöglicht es, dass der gleiche Code auf drei verschiedenen Plattformen ohne Änderungen ausgeführt werden kann.

1. Als eigenständiges Python-Programm, das von "außen" auf ein lokal oder im Netzwerk installiertes RFEM 6 zugreift.
2. In der internen Skript-Konsole von RFEM 6.
3. In der Dlubal-Cloud.

Eigenständiges Programm

Auf Ihrem Computer ist ein normales RFEM 6 installiert. Ihr Python-Programm kommuniziert über API II mit RFEM.

Skript-Konsole

Ihr Skript wird direkt in der Skript-Konsole von RFEM ausgeführt.

Dlubal-Cloud

Für diesem Anwendungsfall muss überhaupt kein RFEM lokal installiert sein. Sie schreiben Ihr Anwendungsprogramm, das mit einem Server in der Dlubal-Cloud kommuniziert. Ihr Anwendungsprogramm generiert Struktur- und Belastungsdaten auf dem Server. Auf dem Server wird die Berechnung durchgeführt. Ihr Anwendungsprogramm liest die Ergebnisse aus der Berechnung und wertet die aus.

Was ändert sich in der Abrechnung?

Für die Nutzung des alten API I wurde eine monatliche Nutzungsgebühr abgerechnet. Die war unabhängig von der tatsächlichen Nutzung.

Mit dem neue API II ändert sich das in ein nutzungsabhängiges Abrechnungsmodell. Das bedeutet, dass der Aufruf einiger bestimmter API-Funktionen kostenpflichtig ist. Abgerechnet wird das in Dlubal-Credits. Diese können im Webshop erworben werden.

API-Key generieren

Für die Nutzung des API II ist zusätzlich zur Webservice-Abo ein API-Key notwendig. Ein API-Key ist ein Stück Text, der zur Identifizierung und Authentifizierung dient.

Die API-Keys kann der Nutzer im Extranet generieren.

Jeder der generierten API-Keys ist der Firma zugeordnet. Das heißt, jeder Nutzer, der der Firma zugeordnet ist, kann die Keys nutzen.

Es ist möglich und oft auch sinnvoll, mehrere API-Keys zu generieren. Dadurch entstehen keine weiteren Kosten. Sinnvoll ist es beispielsweise, für jedes Projekt einen eigenen Key zu generieren. Dadurch kann der Anwender in seiner internen Abrechnung zwischen einzelnen Projekten unterschieden.

Installation der Schnittstelle

Das Paket für die Schnittstelle ist über PiPI verfügbar. Mit dem folgenden Befehl installieren Sie das Paket:

pip install dlubal.api

Programm-Beispiel

In einem kleinen Beispiel wird die Nutzung des neuen API II demonstriert. Es wird ein Kragträger erzeugt, der aus einem IPE 200 besteht.

Hier der Programm-Code:

import dlubal.api.rfem as rfem

with rfem.Application() as rfem_app:

    rfem_app.create_model(name='cantilever')
    rfem_app.delete_all_objects()

    inf = float('inf')

    structure = [
        rfem.structure_core.Material(
            no=1,
            name='S235'
        ),
        rfem.structure_core.Section(
            no=1,
            name='IPE 200',
            material=1
        ),
        rfem.structure_core.Node(
            no=1
        ),
        rfem.structure_core.Node(
            no=2,
            coordinate_1=6.0
        ),
        rfem.structure_core.Line(
            no=1,
            definition_nodes=[1,2]
        ),
        rfem.structure_core.Member(
            no=1,
            line=1,
            section_start=1
        ),
        rfem.types_for_nodes.NodalSupport(
            no=1,
            nodes=[1],
            spring_x=inf,
            spring_y=inf,
            spring_z=inf,
            rotational_restraint_x=inf,
            rotational_restraint_y=inf,
            rotational_restraint_z=inf
        ),
    ]

    rfem_app.create_object_list(structure)

Zunächst wird die RFEM-Bibliothek importiert.

Mit dem with-Befehl wird die Instanz rfem_app von dieser Klasse angelegt. Als Argument von rfem.Application() könne der API-Key übergeben werden. Aus Sicherheitsgründen wird aber davon abgeraten. Statt dessen sollte der API-Key in einer config.ini abgelegt werden. Wie das genau funktioniert ist in der ausführlichen Dokumentation des API II erklärt:

• Documentation API II

In der nächsten Zeile wird mit der Methode rfem_app.create_model(name='cantilever') ein neues RFEM-Model angelegt. Der Modellname kann als Parameter übergeben werden.

In den nächsten Programmzeilen unterscheidet sich das neue API II grundsätzlich vom der "alten" Vorgehensweise im API I. In der Liste structure werden zunächst einmal die Strukturelemente definiert. Dann werden diese gemeinsam mit den Befehl rfem_app.create_object_list(structure) übergeben.