Guide de démarrage rapide

Mettez-vous en route en quelques minutes

Suivez ce guide étape par étape pour effectuer vos premiers appels API réussis vers mindzieStudio et commencer à intégrer les capacités de process mining dans vos applications.

Prérequis

• Identifiants API : jeton d'accès, ID du locataire (tenant) et ID du projet
• URL de base : point d'accès API de votre instance mindzie
• Accès HTTPS : connexion sécurisée à votre instance mindzie
• Environnement de développement : langage de programmation et client HTTP de votre choix

Vous n'avez pas encore d'identifiants ? Consultez le Guide d'authentification pour apprendre comment obtenir vos identifiants d'accès API.

Étape 1 : Tester la connectivité de base

Commencez par tester la connectivité de base pour vous assurer que votre instance mindzie est accessible :

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

Réponse attendue :

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

Étape 2 : Vérifier l'authentification

Testez vos identifiants d'authentification avec l'endpoint ping authentifié :

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"

Réponse attendue :

{
  "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"]
}

Étape 3 : Votre premier appel API

Effectuons un appel API pratique pour récupérer l’historique des actions :

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"

Exemple de réponse :

{
  "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
  }
}

Exemples spécifiques aux langages

JavaScript

Utilisez fetch API ou axios pour les applications web modernes et les backends Node.js.

Python

Utilisez la bibliothèque requests pour les workflows data science et l’automatisation backend.

C#/.NET

Utilisez HttpClient pour les applications d’entreprise et les microservices.

Exemple JavaScript

Exemple complet utilisant JavaScript moderne et fetch API :

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

// Fonction helper pour les requêtes API
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('Échec de l’appel API :', error);
    throw error;
  }
}

// Exemple d'utilisation
async function quickStartExample() {
  try {
    // 1. Tester la connectivité
    console.log('Test de la connectivité...');
    const pingResult = await callMindzieAPI('/Action/ping');
    console.log('Ping réussi :', pingResult);

    // 2. Tester l'authentification
    console.log('Test de l’authentification...');
    const authResult = await callMindzieAPI('/Action/ping/authenticated');
    console.log('Authentification réussie :', authResult);

    // 3. Récupérer l’historique des actions
    console.log('Récupération de l’historique des actions...');
    const history = await callMindzieAPI('/Action/history?limit=5');
    console.log('Historique des actions :', history);

    console.log('Démarrage rapide terminé avec succès !');
    return history;
  } catch (error) {
    console.error('Démarrage rapide échoué :', error);
    throw error;
  }
}

// Exécuter l’exemple
quickStartExample();

Exemple Python

Exemple complet utilisant la bibliothèque requests de Python :

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]:
        """Effectue un appel API vers 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"Échec de l’appel API : {e}")
            raise

    def run_quick_start(self):
        """Exécute la séquence de démarrage rapide"""
        print("Démarrage rapide mindzie API…")

        try:
            # 1. Tester la connectivité
            print("1. Test de la connectivité...")
            ping_result = requests.get(f"{self.base_url}/api/Action/ping")
            ping_result.raise_for_status()
            print(f"   Connectivité OK : {ping_result.json()}")

            # 2. Tester l'authentification
            print("2. Test de l’authentification...")
            auth_result = self.call_api('/api/Action/ping/authenticated')
            print(f"   Authentification OK : {auth_result['status']}")

            # 3. Récupérer l’historique des actions
            print("3. Récupération de l’historique des actions...")
            history = self.call_api('/api/Action/history?limit=5')
            print(f"   {len(history['actions'])} actions récupérées")

            print("Démarrage rapide terminé avec succès !")
            return history

        except Exception as e:
            print(f"Démarrage rapide échoué : {e}")
            raise

# Exemple d’utilisation
if __name__ == "__main__":
    # Configurez vos identifiants
    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'
    )

    # Lancez le démarrage rapide
    result = quick_start.run_quick_start()
    print(f"Résultat final : {json.dumps(result, indent=2)}")

Exemple C#/.NET

Exemple complet utilisant HttpClient en C# :

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($"Échec de l’appel API : {ex.Message}");
            throw;
        }
    }

    public async Task RunQuickStartAsync()
    {
        Console.WriteLine("Démarrage rapide mindzie API...");

        try
        {
            // 1. Tester la connectivité
            Console.WriteLine("1. Test de la connectivité...");
            using var pingClient = new HttpClient();
            var pingResponse = await pingClient.GetAsync($"{_baseUrl}/api/Action/ping");
            pingResponse.EnsureSuccessStatusCode();
            Console.WriteLine("   Connectivité OK");

            // 2. Tester l'authentification
            Console.WriteLine("2. Test de l’authentification...");
            var authResult = await CallApiAsync<AuthResponse>("/api/Action/ping/authenticated");
            Console.WriteLine($"   Authentification OK : {authResult.Status}");

            // 3. Récupérer l’historique des actions
            Console.WriteLine("3. Récupération de l’historique des actions...");
            var history = await CallApiAsync<ActionHistoryResponse>("/api/Action/history?limit=5");
            Console.WriteLine($"   {history.Actions.Length} actions récupérées");

            Console.WriteLine("Démarrage rapide terminé avec succès !");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Démarrage rapide échoué : {ex.Message}");
            throw;
        }
    }

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

// Modèles de données
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; }
}

// Utilisation
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();
        }
    }
}

Problèmes courants et solutions

Échecs d’authentification

• 401 Unauthorized : Vérifiez que votre jeton d’accès est correct et non expiré
• 403 Forbidden : Vérifiez les IDs tenant/projet et les permissions utilisateur
• 400 Bad Request : Assurez-vous que tous les en-têtes nécessaires sont inclus

Problèmes de connexion

• Timeouts réseau : Vérifiez les paramètres du pare-feu et la connectivité réseau
• Erreurs SSL/TLS : Vérifiez la validité du certificat et la configuration HTTPS
• Résolution DNS : Confirmez que l’URL de l’instance mindzie est correcte

Limitation de débit (Rate Limiting)

• 429 Too Many Requests : Implémentez une logique de retry avec backoff exponentiel
• Surveillez les limites : Vérifiez les en-têtes de réponse pour les informations sur les limites
• Optimisez les requêtes : Utilisez la pagination et le filtrage pour réduire les appels API

Étapes suivantes

Félicitations ! Vous avez réussi le démarrage rapide de mindzieAPI. Explorez ensuite l’API Actions ou l’API Blocks pour commencer à bâtir des intégrations puissantes.