Python

Schnellstart

Diese Anleitung zeigt dir, wie du das mittwald API Python SDK verwendest. Das Beispielskript demonstriert Authentifizierung und das Abrufen von Server-Informationen.

1. Installation

Stelle sicher, dass Python 3.10+ installiert ist, und installiere die benötigten Pakete:

user@local $ pip install mittwald-api-client python-dotenv

mittwald-api-client ist das generierte SDK.
python-dotenv lädt Umgebungsvariablen aus einer .env-Datei.

2. Zugangsdaten vorbereiten

Lege im Projektverzeichnis eine Datei namens .env mit folgendem Inhalt an:

API_TOKEN=dein-api-token
SERVER_ID=deine-server-id

Deinen API-Token findest du im mittwald Verwaltungsbereich.
SERVER_ID ist die UUID eines Projekts oder Servers, auf den du Zugriff hast.

3. Anwendungsbeispiel

Speichere das folgende Skript als api_client_test.py:

import os
import sys

from dotenv import load_dotenv

from mittwald_api_client import AuthenticatedClient
from mittwald_api_client.api.project import project_get_server


def main():
    """
    Frisch generierten API-Client testen: Authentifizierten Client aus Umgebungsvariablen einrichten
    und Server-Informationen abrufen.
    """

    load_dotenv()

    API_TOKEN = os.getenv("API_TOKEN")
    SERVER_ID = os.getenv("SERVER_ID")

    if API_TOKEN is None or SERVER_ID is None:
        print("API_TOKEN oder SERVER_ID fehlt. Bitte prüfe deine Umgebung.")
        sys.exit(1)

    client = AuthenticatedClient(
        base_url="https://api.mittwald.de",
        token=API_TOKEN,
        follow_redirects=True,  # Die mittwald API kann HTTP 308 Redirects zurückgeben.
    )

    with client as myclient:
        res = project_get_server.sync_detailed(
            client=myclient,
            server_id=SERVER_ID,
        )

    print("Antwort des Client-Calls:")
    print(res)
    print("---")

if __name__ == '__main__':
    main()

4. Beispiel ausführen

Führe das Skript aus, um einen API-Aufruf zu machen:

(venv) user@local $ python api_client_test.py

Sind die Umgebungsvariablen und dein Token korrekt, zeigt das Skript das Ergebnis des API-Aufrufs.
Fehlen benötigte Variablen, erscheint eine entsprechende Hinweismeldung.

Weitere Schritte

Du kannst das SDK weiter erkunden, zum Beispiel über die Module mittwald_api_client.api und mittwald_api_client.models.
Für Automatisierung, Overlays und CI/CD schau dir den erweiterten Leitfaden an.
Die vollständige API-Dokumentation findest du in der mittwald OpenAPI-Spezifikation.

Codegenerierung – Python API Client

Anforderungen:

Python-Installation (Version 3.10+ empfohlen)
Grundkenntnisse in Bash, Python, pip und virtuellen Umgebungen

Ein Python-API-Client kann mit dem openapi-python-client-Modul generiert werden.

Da der Client selbst zu 100% generiert wird, konzentrieren wir uns auf die Erstellung einer Pipeline für automatisierte Client-Erstellung, Release und Updates. Im Folgenden beginnen wir mit dem manuellen Prozess zur Veranschaulichung – Automatisierung und Wartung werden im nächsten Abschnitt behandelt.

Einen Python mittwald API Client erstellen

Bevor du den Workflow automatisierst, beginne damit, manuell einen Client in deiner Konsole zu generieren. Erstelle zunächst deinen Projektordner, richte eine virtuelle Python-Umgebung ein und installiere den Client-Generator:

user@local $ mkdir python-api-client
user@local $ cd python-api-client
user@local $ python3 -m venv venv
user@local $ source venv/bin/activate
(venv) user@local $ pip install openapi-python-client python-dotenv

Die OpenAPI-Spezifikation herunterladen

user@local $ curl --location --fail --silent 'https://api.mittwald.de/v2/openapi.json' > openapi.json

(Optional) Spezifikation per Overlay anpassen

Du kannst die rohe OpenAPI-Spezifikation direkt nutzen, um einen API-Client zu erstellen. Oft ist es jedoch sinnvoll, die Spezifikation vorher anzupassen, um den Client individueller zu gestalten.

Da Overlays deklarativ sind, kann es je nach Anwendungsfall notwendig sein, eigene Logik zu verwenden, um diese Overlays zu generieren.

Hier ein Beispiel für ein Overlay:

{
  "overlay": "1.1.0",
  "info": {
    "title": "Overlay: Entferne veraltete und unerwünschte Operationen",
    "version": "1.0.0",
    "description": "Entfernt veraltete Operationen und – falls Tags angegeben sind – nicht passende Operationen; löscht leere Pfade. Siehe overlay_generator.py für die Business-Logik."
  },
  "actions": [
    {
      "target": "$.paths['/v2/appinstallations/{appInstallationId}/actions/{action}'].post",
      "remove": true,
      "description": "Wurde wegen Veralterung oder Filter entfernt"
    }
  ]
}

Die Herausforderung beim Erstellen von Overlays ist es, die passenden JSONPath-Selektoren für das target-Feld in den Aktionen zu bestimmen.

Beispiel für das Anwenden eines Overlays mit oas-patcher:

# Overlay-Generator erstellt "openapi_filter_overlay.json"
(venv) user@local $ python tools/overlay_generator.py openapi.json openapi_filter_overlay.json

# Overlay anwenden, erstellt "openapi_from_overlay.json"
(venv) user@local $ oas-patch overlay openapi.json openapi_filter_overlay.json -o openapi_from_overlay.json

Die resultierende openapi_from_overlay.json ist entsprechend den im openapi_filter_overlay.json definierten Aktionen gefiltert. Halte diese Dateien zusammen mit der Basis-openapi.json bereit, um Builds später exakt reproduzieren zu können.

Den Code-Generator ausführen

(venv) user@local $ openapi-python-client generate --path ./openapi.json

Der Generator kann Warnungen ausgeben. Wie mit Warnungen umgehen:

Wenn dein Projekt die API-Teile benötigt, die eine Warnung auslösen, musst du das zugrunde liegende Problem beheben.
Wenn du diese Endpunkte oder Features nicht benötigst, kannst du die Warnungen sicher ignorieren.
Für blockierende Probleme in der OpenAPI-Spezifikation melde diese bitte über den mittwald Feature Requests Tracker.

Halte den Wartungsaufwand gering; vermeide es, die OpenAPI-Spezifikation zu patchen, es sei denn, es ist unbedingt notwendig. Bevorzuge Generator-Konfigurationsanpassungen.

Den generierten Client installieren und testen

Nach der Generierung erscheint ein mittwald-api-client-Ordner in deinem Projektverzeichnis. Installiere ihn zum Testen:

(venv) user@local $ pip install -e ./mittwald-api-client

Schaue dir die generierte mittwald-api-client/README.md an, um loszulegen. Teste deinen Client mit echten Business Cases; hier ist ein Starter-Skript für eine einfache GET-Operation:

import os
import sys
from dotenv import load_dotenv
from mittwald_api_client import AuthenticatedClient
from mittwald_api_client.api.project import project_get_server

def main():
    """Frisch generierten API-Client testen: Authentifizierten Client aus Umgebung einrichten und Server-Info abrufen."""
    load_dotenv()
    API_TOKEN = os.getenv("API_TOKEN")
    SERVER_ID = os.getenv("SERVER_ID")
    if API_TOKEN is None or SERVER_ID is None:
        print("API_TOKEN oder SERVER_ID fehlt. Bitte prüfe deine Umgebung.")
        sys.exit(1)
    client = AuthenticatedClient(
        base_url="https://api.mittwald.de",
        token=API_TOKEN,
        follow_redirects=True,  # Die mittwald API kann HTTP 308 Redirects zurückgeben, die der Client standardmäßig nicht erwartet
    )
    with client as myclient:
        res = project_get_server.sync_detailed(
            client=myclient,
            server_id=SERVER_ID,
        )
    print("Ergebnis des Client-Calls:")
    print(res)
    print("---")

if __name__ == '__main__':
    main()

# Example .env file for local development
API_TOKEN=your-api-token-here
SERVER_ID=your-server-id-here

Nicht-GET-Operationen testen – Beispiel POST

Um andere HTTP-Methoden (POST, PATCH, DELETE) zu verwenden, musst du Request-Body-Objekte konstruieren. Hier ist ein Beispiel für eine POST-Operation:

import os
import sys
import time

from dotenv import load_dotenv

from mittwald_api_client import AuthenticatedClient
from mittwald_api_client.api.project import project_create_project
from mittwald_api_client.models import ProjectCreateProjectBody


def main():
    """
    Frisch generierten API-Client testen: Authentifizierten Client aus Umgebung
    einrichten und Server-Informationen abrufen
    """

    load_dotenv()

    API_TOKEN = os.getenv("API_TOKEN")
    SERVER_ID = os.getenv("SERVER_ID")

    if API_TOKEN is None or SERVER_ID is None:
        print("API_TOKEN oder SERVER_ID fehlt. Bitte prüfe deine Umgebung.")
        sys.exit(1)

    client = AuthenticatedClient(
        base_url="https://api.mittwald.de",
        token=API_TOKEN,
        follow_redirects=True,  # API kann 308 aka permanente Redirects zurückgeben, die der Client standardmäßig NICHT erwartet
    )

    with client as myclient:
        res = project_create_project.sync(
            client=myclient,
            server_id=SERVER_ID,
            body=ProjectCreateProjectBody.from_dict({
                "description": f"python_post_test_project_{time.time()}"
            })
        )

    print("Ergebnis des Client-Calls:")
    print(res)
    print("---")

if __name__ == '__main__':
    main()

Prüfe die generierten Client-Modelle auf erforderliche Felder und Strukturen.

Nach der Generierung – Aufräumen

Überprüfe generierte Tests, README und Beispiel-Skripte, bevor du publizierst oder mit deiner Haupt-App integrierst.
Räume nicht benötigte Dateien auf, damit klar und fokussiert ist, was du auslieferst.

Package Naming – Hinweis zu Konflikten

Python mittwald API Client veröffentlichen

Die Veröffentlichung von API-Clients hängt von deinem Use Case ab; für hochspezialisierte Projekte ist eine Veröffentlichung möglicherweise nicht erforderlich. Für allgemeine oder wiederverwendbare Clients ist das öffentliche PyPI der Standard.

Folge den Anweisungen in der generierten README für die Veröffentlichung. Beispiel für test PyPI:

(venv) user@local $ poetry config repositories.testpypi https://test.pypi.org/simple/
(venv) user@local $ poetry config pypi-token.testpypi <TOKEN-HERE>
(venv) user@local $ cd mittwald-api-client
(venv) user@local $ poetry publish --build -r testpypi

Nach erfolgreicher Veröffentlichung:

(venv) user@local $ cd my-python-mittwald-project
(venv) user@local $ pip install -i https://test.pypi.org/simple/ mittwald-api-client

Für Automatisierung und Wartung fahre bitte mit dem Wartungs- & Pipeline-Abschnitt fort.

Python API Client-Generierung und -Release mit GitHub Actions automatisieren

Um sicherzustellen, dass dein Python mittwald API Client immer auf dem neuesten Stand mit den neuesten API-Änderungen bleibt, kannst du eine CI/CD-Pipeline mit GitHub Actions einrichten. Dieser Workflow wird automatisch den Client aus der OpenAPI-Spezifikation regenerieren, testen und – optional – neue Versionen nach einem regelmäßigen Zeitplan (z. B. wöchentlich) veröffentlichen.

Voraussetzungen

Dein Projekt-Repository auf GitHub.
Python 3.10+ in deinem Workflow spezifiziert.
Zugang zur mittwald OpenAPI-Spezifikations-URL.
Publishing-Credentials (z. B. PyPI-Token) als GitHub-Repository-Secrets gespeichert.

Erforderliche Dateien zum Repo hinzufügen

Platziere deine Generator-Config-Datei (z. B. .openapi-python-client-config.yml) im Projekt-Root, falls erforderlich.
Behalte deine Test-Skripte und Beispiel-.env.example-Dateien eingecheckt, aber committe niemals echte Credentials.

Beispiel GitHub Actions Workflow

Erstelle eine Datei unter .github/workflows/client-release.yml:

name: API Client Regeneration and Release

permissions:
  contents: write
  id-token: write # Required for OIDC with PyPI trusted publisher

on:
  schedule:
    - cron: "0 4 * * 1" # Runs every Monday at 04:00 UTC
  workflow_dispatch: # Allows manual trigger

jobs:
  build-and-release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4 # v4 is latest stable at time of writing
        with:
          fetch-depth: 0 # Fetch all history and tags

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Upgrade pip, install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements_build.txt

      - name: Download OpenAPI specification
        run: curl --location --fail --silent 'https://api.mittwald.de/v2/openapi.json' > openapi.json

      - name: Filter deprecated endpoints from OpenAPI spec
        run: |
          echo "Filtering specs ..."
          python tools/filter_openapi_deprecated.py openapi.json openapi.json

      - name: Set dynamic version in OpenAPI spec
        run: |
          LAST_TAG=$(git tag --sort=-creatordate | head -n 1)
          python tools/adjust_openapi_version.py openapi.json $LAST_TAG

      - name: Regenerate Client
        run: openapi-python-client generate --overwrite --path ./openapi.json

      - name: Install Generated Client for Testing
        run: pip install -e ./mittwald-api-client

      - name: Run Tests
        run: |
          python smoke_test.py

      - name: Extract version from openapi.json
        id: get_version
        run: |
          VERSION=$(jq -r '.info.version' openapi.json)
          echo "RELEASE_VERSION=$VERSION" >> $GITHUB_ENV

      - name: Commit regenerated client
        run: |
          git config user.name "github-actions"
          git config user.email "github-actions@github.com"
          git add mittwald-api-client openapi.json
          git commit -m "chore: update generated API client ${RELEASE_VERSION}" || echo "No changes to commit"
          git push origin HEAD:${{ github.ref }}

      - name: Build Package
        run: |
          cd mittwald-api-client
          poetry build

      - name: List build output
        run: |
          cd mittwald-api-client
          ls -la dist

      - name: Publish to TestPyPI using OIDC
        if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
        uses: pypa/gh-action-pypi-publish@v1.13.0
        with:
          repository-url: https://test.pypi.org/legacy/
          packages-dir: mittwald-api-client/dist
          verbose: true

      - name: Create and push git tag
        if: success()
        run: |
          git config user.name "github-actions"
          git config user.email "github-actions@github.com"
          git tag "v$RELEASE_VERSION"
          git push origin "v$RELEASE_VERSION"
        env:
          RELEASE_VERSION: ${{ env.RELEASE_VERSION }}

      - name: Upload built packages for inspection
        uses: actions/upload-artifact@v4
        with:
          name: built-dist
          path: mittwald-api-client/dist/

Best Practices und Tipps

Zeitplan weise wählen:
Verwende die cron-Scheduling-Syntax, um zu steuern, wie häufig Releases stattfinden (z. B. wöchentlich, täglich).
Secrets sichern:
Konfiguriere deinen Workflow als Trusted Publisher auf PyPI und verwende die moderne gh-action-pypi-publish-Action. Dies ist die aktuelle Methode, um sichere und tokenlose Release-Pipelines zu erstellen.
Testing:
Teste den regenerierten Client immer vor der Veröffentlichung. Füge aussagekräftige Business-Case-Tests hinzu, um zu verhindern, dass defekte Packages veröffentlicht werden.
Manuelle Trigger:
Das workflow_dispatch-Event ermöglicht es Maintainern, Releases bei Bedarf auszulösen.
Versionskontrolle:
Erwäge, Releases zu taggen oder Versionsnummern basierend auf API-/Spec-Änderungen zu aktualisieren.
Artifact-Upload: Füge einen upload-artifact-Schritt hinzu, um Build-Output für Debugging und Inspektion zu bewahren.

Den Workflow erweitern

Du kannst Schritte hinzufügen, um automatisch Release Notes, Tags oder Changelogs zu erstellen.
Unterstütze mehrere Python-Versionen durch Matrix-Builds, falls erforderlich.
Integriere Benachrichtigungen oder Fehlschlag-Alarme über Slack, E-Mail, etc.

Mit diesem Setup bleibt dein API-Client aktuell, getestet und einfach verteilbar – ohne manuelle Intervention.

Schnellstart​

1. Installation​

2. Zugangsdaten vorbereiten​

3. Anwendungsbeispiel​

4. Beispiel ausführen​

Weitere Schritte​

Codegenerierung – Python API Client​

Einen Python mittwald API Client erstellen​

Die OpenAPI-Spezifikation herunterladen​

(Optional) Spezifikation per Overlay anpassen​

Den Code-Generator ausführen​

Den generierten Client installieren und testen​

Nicht-GET-Operationen testen – Beispiel POST​

Nach der Generierung – Aufräumen​

Package Naming – Hinweis zu Konflikten​

Python mittwald API Client veröffentlichen​

Python API Client-Generierung und -Release mit GitHub Actions automatisieren​

Voraussetzungen​

Erforderliche Dateien zum Repo hinzufügen​

Beispiel GitHub Actions Workflow​

Best Practices und Tipps​

Den Workflow erweitern​