SDKs

Archyl fournit des SDKs officiels pour Node.js et Python. Ce sont deux surcouches légères de l'API REST qui gèrent pour vous l'authentification, la sérialisation et la gestion des erreurs.

Installation

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

Démarrage rapide

Node.js

import { ArchylClient } from "@archyl/sdk";

const client = new ArchylClient({
  apiKey: process.env.ARCHYL_API_KEY,
  organizationId: "your-org-id",
});

// List projects
const projects = await client.projects.list();

// Get C4 model
const model = await client.projects.getC4Model("project-id");

// Compute drift score
const drift = await client.governance.computeDrift("project-id");

// Create an ADR
const adr = await client.docs.createADR("project-id", {
  title: "Use PostgreSQL for persistence",
  status: "accepted",
  context: "We need a relational database for transactional data.",
  decision: "Adopt PostgreSQL 16 as the primary datastore.",
  consequences: "Team must learn PostgreSQL-specific features.",
});

Python

from archyl import ArchylClient

client = ArchylClient(
    api_key=os.environ["ARCHYL_API_KEY"],
    organization_id="your-org-id",
)

# List projects
projects = client.projects.list()

# Get C4 model
model = client.projects.get_c4_model("project-id")

# Compute drift score
drift = client.governance.compute_drift("project-id")

# Create an ADR
adr = client.docs.create_adr("project-id",
    title="Use PostgreSQL for persistence",
    status="accepted",
    context="We need a relational database for transactional data.",
    decision="Adopt PostgreSQL 16 as the primary datastore.",
    consequences="Team must learn PostgreSQL-specific features.",
)

Référence de l'API

Projets

Méthode Description
projects.list() Liste tous les projets de l'organisation
projects.get(projectId) Récupère un projet par son ID
projects.create(data) Crée un nouveau projet
projects.getC4Model(projectId) Récupère le modèle C4 complet d'un projet
projects.getAgentContext(projectId) Récupère le contexte architectural (règles, radar technologique, décisions)

Modèle C4

Méthode Description
c4.createSystem(projectId, data) Crée un système
c4.updateSystem(projectId, systemId, data) Met à jour un système
c4.createContainer(projectId, systemId, data) Crée un conteneur
c4.updateContainer(projectId, containerId, data) Met à jour un conteneur
c4.createComponent(projectId, containerId, data) Crée un composant
c4.createRelationship(projectId, data) Crée une relation entre des éléments
c4.listRelationships(projectId) Liste toutes les relations

Gouvernance

Méthode Description
governance.runConformanceCheck(projectId, data) Exécute les règles de conformité sur des fichiers
governance.getReport(checkId) Récupère le rapport complet d'une vérification
governance.listRules() Liste toutes les règles de conformité
governance.createRule(data) Crée une règle de conformité
governance.getStats(projectId?) Récupère les statistiques de conformité
governance.computeDrift(projectId) Calcule le score de dérive d'un projet
governance.getDriftScore(projectId) Récupère le dernier score de dérive
governance.getDriftHistory(projectId) Récupère l'historique du score de dérive dans le temps

Métriques DORA

Méthode Description
dora.getMetrics(projectId) Récupère les métriques DORA actuelles
dora.getTrend(projectId) Récupère l'évolution des métriques DORA dans le temps

Documentation

Méthode Description
docs.listADRs(projectId) Liste les Architecture Decision Records
docs.createADR(projectId, data) Crée un ADR
docs.listReleases(projectId) Liste les releases
docs.createRelease(projectId, data) Crée une release
docs.listChangeRequests(projectId) Liste les demandes de changement
docs.createChangeRequest(projectId, data) Crée une demande de changement

Gestion des erreurs

Les deux SDKs lèvent des erreurs typées qui contiennent le code de statut HTTP et le détail de l'erreur renvoyé par l'API.

Node.js

import { ArchylError } from "@archyl/sdk";

try {
  await client.projects.get("nonexistent-id");
} catch (error) {
  if (error instanceof ArchylError) {
    console.error(error.status); // 404
    console.error(error.code); // "NOT_FOUND"
    console.error(error.message); // "Project not found"
  }
}

Python

from archyl import ArchylError

try:
    client.projects.get("nonexistent-id")
except ArchylError as e:
    print(e.status)   # 404
    print(e.code)     # "NOT_FOUND"
    print(e.message)  # "Project not found"

Codes de statut courants :

Code Signification
400 Requête invalide - Paramètres invalides
401 Non autorisé - Clé API invalide ou manquante
403 Interdit - Permissions insuffisantes
404 Non trouvé - La ressource n'existe pas
429 Trop de requêtes - Limite de débit dépassée
500 Erreur interne du serveur

Configuration

URL de base personnalisée

Pour les instances Archyl auto-hébergées, passez une baseUrl personnalisée :

const client = new ArchylClient({
  apiKey: "your-api-key",
  organizationId: "your-org-id",
  baseUrl: "https://archyl.your-company.com/api/v1",
});

client = ArchylClient(
    api_key="your-api-key",
    organization_id="your-org-id",
    base_url="https://archyl.your-company.com/api/v1",
)

Code source

Les deux SDKs sont open source :

Étapes suivantes