Documentation
Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Interface

API de Découverte v2

Découvrir et explorer les endpoints disponibles dans Dokos via l'API de découverte v2.

API de Découverte v2

L'API de découverte v2 permet aux développeurs d'explorer dynamiquement les endpoints disponibles dans Dokos. Cette API est conçue pour faciliter l'intégration et le développement d'applications tierces en fournissant une vue structurée des routes et des fonctionnalités exposées.

::: warning Attention Cette API est non stable et réservée aux développeurs. Aucune garantie de compatibilité n'est offerte pour les versions futures. Pour une documentation stable, consultez les guides officiels. :::

Accès à l'API

L'API de découverte v2 est accessible via l'endpoint suivant :

GET /api/v2/discovery

Restrictions d'accès

L'accès à cette API est restreint aux utilisateurs disposant des permissions de développeur. Pour activer cette permission :

  1. Allez dans Utilisateur > Rôle.
  2. Sélectionnez le rôle concerné (par exemple, Développeur).
  3. Cochez la case Accès API de découverte.
  4. Enregistrez.

Structure de la réponse

La réponse de l'API est au format JSON et contient les sections suivantes :

  • routes : Liste des endpoints disponibles, organisés par module.
  • methods : Méthodes HTTP supportées (GET, POST, PUT, DELETE).
  • parameters : Paramètres attendus pour chaque endpoint.
  • examples : Exemples de requêtes et réponses.

Exemple de réponse

{
  "routes": {
    "core": {
      "/api/resource/Client": {
        "methods": ["GET", "POST", "PUT", "DELETE"],
        "parameters": {
          "filters": "Filtres pour la recherche (ex: {\"nom\": \"Maison Verte SARL\"})",
          "fields": "Champs à retourner (ex: [\"nom\", \"email\"])"
        },
        "examples": {
          "GET": {
            "request": "GET /api/resource/Client?fields=[\"nom\"]&filters={\"nom\": \"Maison Verte SARL\"}",
            "response": {
              "data": [
                {
                  "nom": "Maison Verte SARL"
                }
              ]
            }
          }
        }
      }
    }
  }
}

Utilisation avec cURL

Voici comment interroger l'API de découverte v2 avec cURL :

curl -X GET "https://votre-instance.dokos.cloud/api/v2/discovery" \
     -H "Authorization: token VOTRE_CLE_API:VOTRE_CLE_SECRETE"

Cas d'usage

Intégration avec des outils externes

L'API de découverte v2 peut être utilisée pour :

  • Générer automatiquement des clients API : Utilisez les métadonnées pour créer des bibliothèques clientes dans différents langages (Python, JavaScript, etc.).
  • Documenter dynamiquement les endpoints : Intégrez les réponses de l'API dans vos outils de documentation (ex: Swagger, Redoc).
  • Valider des requêtes : Vérifiez la disponibilité et les paramètres des endpoints avant de les appeler.

Exemple : Génération d'un client Python

import requests
import json

# Récupérer les endpoints
discovery_url = "https://votre-instance.dokos.cloud/api/v2/discovery"
response = requests.get(discovery_url, auth=("VOTRE_CLE_API", "VOTRE_CLE_SECRETE"))
endpoints = response.json()

# Générer un client basique
for module, routes in endpoints["routes"].items():
    for route, details in routes.items():
        print(f"def {route.replace('/', '_').replace('-', '_')}(self, **kwargs):")
        print(f"    # {details['methods']} {route}")
        print(f"    return self._request('{details['methods'][0]}', '{route}', kwargs)")

Limitations

  • Pas de compatibilité OpenAPI : Cette API ne fournit pas de spécification OpenAPI. Pour une documentation OpenAPI, utilisez des applications tierces comme frappe_openapi.
  • Changements fréquents : Les endpoints et leur structure peuvent évoluer sans préavis.
  • Pas de support pour les webhooks : Les webhooks ne sont pas inclus dans la réponse.

Bonnes pratiques

  • Cachez les réponses : Comme la structure des endpoints évolue rarement, stockez localement la réponse pour éviter des appels inutiles.
  • Gérez les erreurs : Prévoyez des mécanismes de réessai en cas d'échec de l'appel à l'API.
  • Respectez les permissions : Assurez-vous que les utilisateurs de votre application disposent des rôles appropriés pour accéder aux endpoints.

Diagramme de flux

Voici un aperçu du flux d'utilisation de l'API de découverte v2 :

Ressources complémentaires