Guide de démarrage rapide

Démarrez en quelques minutes

Suivez ce guide étape par étape pour effectuer vos premiers appels API réussis vers mindzieStudio et commencer à intégrer les fonctionnalité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 d’identifiants ? Consultez le Guide d’authentification pour apprendre comment obtenir vos identifiants d’accès API.

Étape 1 : Tester la connectivité basique

Commencez par tester la connectivité basique pour vérifier 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 le point de terminaison 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

Faisons un appel pratique à l’API 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"

Réponse exemple :

{
  "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 serveurs Node.js.

Python

Utilisez la bibliothèque requests pour les flux de travail en 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 utilitaire pour les appels 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('Échec du démarrage rapide :', error);
    throw error;
  }
}

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

Exemple Python

Exemple complet utilisant la bibliothèque Python requests :

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]:
        """Effectuer 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écuter la séquence de démarrage rapide"""
        print("Démarrage du Quick Start 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"Échec du démarrage rapide : {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'
    )

    # Exécutez 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 du Quick Start 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($"Échec du démarrage rapide : {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 Non autorisé : Vérifiez que votre jeton d’accès est correct et non expiré
• 403 Interdit : Vérifiez les IDs de locataire/projet et les permissions utilisateur
• 400 Requête incorrecte : Assurez-vous que tous les en-têtes requis sont inclus

Problèmes de connexion

• Timeout réseau : Vérifiez les paramètres de 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 du taux (rate limiting)

• 429 Trop de requêtes : Implémentez une logique de retry avec backoff exponentiel
• Surveillez les limites : Consultez 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 le nombre d’appels API

Étapes suivantes

Félicitations ! Vous avez réussi le démarrage rapide mindzieAPI. Explorez les Actions API ou Blocks API pour commencer à construire des intégrations puissantes.