Schnellstart-Anleitung

In wenigen Minuten einsatzbereit

Folgen Sie dieser Schritt-für-Schritt-Anleitung, um Ihre ersten erfolgreichen API-Aufrufe an mindzieStudio zu machen und Prozess-Mining-Fähigkeiten in Ihre Anwendungen zu integrieren.

Voraussetzungen

• API-Zugangsdaten: Access-Token, Tenant-ID und Projekt-ID
• Basis-URL: Der API-Endpunkt Ihrer mindzie-Instanz
• HTTPS-Zugang: Sichere Verbindung zu Ihrer mindzie-Instanz
• Entwicklungsumgebung: Ihre bevorzugte Programmiersprache und HTTP-Client

Keine Zugangsdaten? Sehen Sie im Authentifizierungsleitfaden nach, wie Sie Ihre API-Zugangsdaten erhalten.

Schritt 1: Grundlegende Konnektivität testen

Beginnen Sie mit dem Test der grundlegenden Verbindung, um sicherzustellen, dass Ihre mindzie-Instanz erreichbar ist:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping"

Erwartete Antwort:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Schritt 2: Authentifizierung überprüfen

Testen Sie Ihre Authentifizierungsdaten mit dem authentifizierten Ping-Endpunkt:

curl -X GET "https://your-mindzie-instance.com/api/Action/ping/authenticated" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Erwartete Antwort:

{
  "status": "authenticated",
  "timestamp": "2024-01-15T10:30:00Z",
  "tenantId": "12345678-1234-1234-1234-123456789012",
  "projectId": "87654321-4321-4321-4321-210987654321",
  "userId": "user@company.com",
  "permissions": ["read", "write", "admin"]
}

Schritt 3: Ihr erster API-Aufruf

Machen wir einen praktischen API-Aufruf, um die Aktionshistorie abzurufen:

curl -X GET "https://your-mindzie-instance.com/api/Action/history?limit=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-Id: YOUR_TENANT_GUID" \
  -H "X-Project-Id: YOUR_PROJECT_GUID" \
  -H "Content-Type: application/json"

Beispielantwort:

{
  "actions": [
    {
      "actionId": "87654321-4321-4321-4321-210987654321",
      "actionType": "analyze",
      "status": "completed",
      "startTime": "2024-01-15T10:30:00Z",
      "endTime": "2024-01-15T10:32:15Z",
      "duration": 135,
      "userId": "user@company.com"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 1,
    "itemsPerPage": 5
  }
}

Sprachspezifische Beispiele

JavaScript

Verwenden Sie fetch API oder axios für moderne Webanwendungen und Node.js-Backends.

Python

Verwenden Sie die requests-Bibliothek für Data-Science-Workflows und Backend-Automatisierung.

C#/.NET

Verwenden Sie HttpClient für Unternehmensanwendungen und Microservices.

JavaScript-Beispiel

Vollständiges Beispiel mit modernem JavaScript und fetch API:

// Konfiguration
const API_CONFIG = {
  baseURL: 'https://your-mindzie-instance.com/api',
  token: 'YOUR_ACCESS_TOKEN',
  tenantId: 'YOUR_TENANT_GUID',
  projectId: 'YOUR_PROJECT_GUID'
};

// Hilfsfunktion für API-Anfragen
async function callMindzieAPI(endpoint, options = {}) {
  const url = `${API_CONFIG.baseURL}${endpoint}`;

  const defaultHeaders = {
    'Authorization': `Bearer ${API_CONFIG.token}`,
    'X-Tenant-Id': API_CONFIG.tenantId,
    'X-Project-Id': API_CONFIG.projectId,
    'Content-Type': 'application/json'
  };

  try {
    const response = await fetch(url, {
      ...options,
      headers: { ...defaultHeaders, ...options.headers }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('API-Aufruf fehlgeschlagen:', error);
    throw error;
  }
}

// Beispielanwendung
async function quickStartExample() {
  try {
    // 1. Konnektivität testen
    console.log('Teste Konnektivität...');
    const pingResult = await callMindzieAPI('/Action/ping');
    console.log('Ping erfolgreich:', pingResult);

    // 2. Authentifizierung testen
    console.log('Teste Authentifizierung...');
    const authResult = await callMindzieAPI('/Action/ping/authenticated');
    console.log('Authentifizierung erfolgreich:', authResult);

    // 3. Aktionshistorie abrufen
    console.log('Rufe Aktionshistorie ab...');
    const history = await callMindzieAPI('/Action/history?limit=5');
    console.log('Aktionshistorie:', history);

    console.log('Schnellstart erfolgreich abgeschlossen!');
    return history;
  } catch (error) {
    console.error('Schnellstart fehlgeschlagen:', error);
    throw error;
  }
}

// Beispiel ausführen
quickStartExample();

Python-Beispiel

Vollständiges Beispiel mit Python requests-Bibliothek:

import requests
import json
from typing import Dict, Any

class MindzieQuickStart:
    def __init__(self, base_url: str, token: str, tenant_id: str, project_id: str):
        self.base_url = base_url.rstrip('/')
        self.headers = {
            'Authorization': f'Bearer {token}',
            'X-Tenant-Id': tenant_id,
            'X-Project-Id': project_id,
            'Content-Type': 'application/json'
        }

    def call_api(self, endpoint: str, method: str = 'GET', **kwargs) -> Dict[str, Any]:
        """Macht einen API-Aufruf an mindzie"""
        url = f"{self.base_url}{endpoint}"

        try:
            response = requests.request(
                method=method,
                url=url,
                headers=self.headers,
                **kwargs
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API-Aufruf fehlgeschlagen: {e}")
            raise

    def run_quick_start(self):
        """Führt die Schnellstart-Sequenz aus"""
        print("Starte mindzie API Schnellstart...")

        try:
            # 1. Konnektivität testen
            print("1. Teste Konnektivität...")
            ping_result = requests.get(f"{self.base_url}/api/Action/ping")
            ping_result.raise_for_status()
            print(f"   Konnektivität OK: {ping_result.json()}")

            # 2. Authentifizierung testen
            print("2. Teste Authentifizierung...")
            auth_result = self.call_api('/api/Action/ping/authenticated')
            print(f"   Authentifizierung OK: {auth_result['status']}")

            # 3. Aktionshistorie abrufen
            print("3. Rufe Aktionshistorie ab...")
            history = self.call_api('/api/Action/history?limit=5')
            print(f"   {len(history['actions'])} Aktionen abgerufen")

            print("Schnellstart erfolgreich abgeschlossen!")
            return history

        except Exception as e:
            print(f"Schnellstart fehlgeschlagen: {e}")
            raise

# Anwendungsbeispiel
if __name__ == "__main__":
    # Zugangsdaten konfigurieren
    quick_start = MindzieQuickStart(
        base_url='https://your-mindzie-instance.com/api',
        token='YOUR_ACCESS_TOKEN',
        tenant_id='YOUR_TENANT_GUID',
        project_id='YOUR_PROJECT_GUID'
    )

    # Schnellstart ausführen
    result = quick_start.run_quick_start()
    print(f"Endergebnis: {json.dumps(result, indent=2)}")

C#/.NET Beispiel

Vollständiges Beispiel mit C# HttpClient:

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

public class MindzieQuickStart
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;

    public MindzieQuickStart(string baseUrl, string token, string tenantId, string projectId)
    {
        _baseUrl = baseUrl.TrimEnd('/');

        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
        _httpClient.DefaultRequestHeaders.Add("X-Tenant-Id", tenantId);
        _httpClient.DefaultRequestHeaders.Add("X-Project-Id", projectId);
    }

    public async Task<T> CallApiAsync<T>(string endpoint)
    {
        try
        {
            var response = await _httpClient.GetAsync($"{_baseUrl}{endpoint}");
            response.EnsureSuccessStatusCode();

            var content = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<T>(content, new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"API-Aufruf fehlgeschlagen: {ex.Message}");
            throw;
        }
    }

    public async Task RunQuickStartAsync()
    {
        Console.WriteLine("Starte mindzie API Schnellstart...");

        try
        {
            // 1. Konnektivität testen
            Console.WriteLine("1. Teste Konnektivität...");
            using var pingClient = new HttpClient();
            var pingResponse = await pingClient.GetAsync($"{_baseUrl}/api/Action/ping");
            pingResponse.EnsureSuccessStatusCode();
            Console.WriteLine("   Konnektivität OK");

            // 2. Authentifizierung testen
            Console.WriteLine("2. Teste Authentifizierung...");
            var authResult = await CallApiAsync<AuthResponse>("/api/Action/ping/authenticated");
            Console.WriteLine($"   Authentifizierung OK: {authResult.Status}");

            // 3. Aktionshistorie abrufen
            Console.WriteLine("3. Rufe Aktionshistorie ab...");
            var history = await CallApiAsync<ActionHistoryResponse>("/api/Action/history?limit=5");
            Console.WriteLine($"   {history.Actions.Length} Aktionen abgerufen");

            Console.WriteLine("Schnellstart erfolgreich abgeschlossen!");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Schnellstart fehlgeschlagen: {ex.Message}");
            throw;
        }
    }

    public void Dispose()
    {
        _httpClient?.Dispose();
    }
}

// Datenmodelle
public class AuthResponse
{
    public string Status { get; set; }
    public string TenantId { get; set; }
    public string ProjectId { get; set; }
    public string UserId { get; set; }
}

public class ActionHistoryResponse
{
    public ActionItem[] Actions { get; set; }
    public PaginationInfo Pagination { get; set; }
}

public class ActionItem
{
    public string ActionId { get; set; }
    public string ActionType { get; set; }
    public string Status { get; set; }
    public DateTime StartTime { get; set; }
    public DateTime? EndTime { get; set; }
}

public class PaginationInfo
{
    public int CurrentPage { get; set; }
    public int TotalPages { get; set; }
    public int TotalItems { get; set; }
}

// Nutzung
class Program
{
    static async Task Main(string[] args)
    {
        var quickStart = new MindzieQuickStart(
            "https://your-mindzie-instance.com/api",
            "YOUR_ACCESS_TOKEN",
            "YOUR_TENANT_GUID",
            "YOUR_PROJECT_GUID"
        );

        try
        {
            await quickStart.RunQuickStartAsync();
        }
        finally
        {
            quickStart.Dispose();
        }
    }
}

Häufige Probleme & Lösungen

Authentifizierungsfehler

• 401 Unauthorized: Überprüfen Sie, ob Ihr Access-Token korrekt und nicht abgelaufen ist
• 403 Forbidden: Prüfen Sie Tenant-/Projekt-IDs und Benutzerberechtigungen
• 400 Bad Request: Stellen Sie sicher, dass alle erforderlichen Header enthalten sind

Verbindungsprobleme

• Netzwerk-Timeouts: Überprüfen Sie Firewall-Einstellungen und Netzwerkverbindung
• SSL/TLS-Fehler: Prüfen Sie die Gültigkeit des Zertifikats und die HTTPS-Konfiguration
• DNS-Auflösung: Vergewissern Sie sich, dass die URL der mindzie-Instanz korrekt ist

Rate-Limiting

• 429 Too Many Requests: Implementieren Sie eine exponentielle Backoff-Wiederholungslogik
• Rate-Limits überwachen: Prüfen Sie Antwort-Header auf Rate-Limit-Informationen
• Anfragen optimieren: Verwenden Sie Paginierung und Filter zur Reduzierung der API-Aufrufe

Nächste Schritte

Herzlichen Glückwunsch! Sie haben den mindzieAPI Schnellstart erfolgreich abgeschlossen. Erkunden Sie als Nächstes die Actions API oder die Blocks API, um leistungsstarke Integrationen zu erstellen.