SDKs

Archyl bietet offizielle SDKs für Node.js und Python. Beide sind schlanke Wrapper um die REST-API, die Authentifizierung, Serialisierung und Fehlerbehandlung für Sie übernehmen.

Installation

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

Schnellstart

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.",
)

API-Referenz

Projekte

Methode Beschreibung
projects.list() Alle Projekte der Organisation auflisten
projects.get(projectId) Ein Projekt anhand seiner ID abrufen
projects.create(data) Ein neues Projekt erstellen
projects.getC4Model(projectId) Das vollständige C4-Modell eines Projekts abrufen
projects.getAgentContext(projectId) Den Architekturkontext abrufen (Regeln, Technologie-Radar, Entscheidungen)

C4-Modell

Methode Beschreibung
c4.createSystem(projectId, data) Ein System erstellen
c4.updateSystem(projectId, systemId, data) Ein System aktualisieren
c4.createContainer(projectId, systemId, data) Einen Container erstellen
c4.updateContainer(projectId, containerId, data) Einen Container aktualisieren
c4.createComponent(projectId, containerId, data) Eine Komponente erstellen
c4.createRelationship(projectId, data) Eine Beziehung zwischen Elementen erstellen
c4.listRelationships(projectId) Alle Beziehungen auflisten

Governance

Methode Beschreibung
governance.runConformanceCheck(projectId, data) Konformitätsregeln auf Dateien anwenden
governance.getReport(checkId) Den vollständigen Bericht einer Prüfung abrufen
governance.listRules() Alle Konformitätsregeln auflisten
governance.createRule(data) Eine Konformitätsregel erstellen
governance.getStats(projectId?) Konformitätsstatistiken abrufen
governance.computeDrift(projectId) Den Drift-Score eines Projekts berechnen
governance.getDriftScore(projectId) Den aktuellsten Drift-Score abrufen
governance.getDriftHistory(projectId) Den Verlauf des Drift-Scores über die Zeit abrufen

DORA-Metriken

Methode Beschreibung
dora.getMetrics(projectId) Aktuelle DORA-Metriken abrufen
dora.getTrend(projectId) Den Trend der DORA-Metriken über die Zeit abrufen

Dokumentation

Methode Beschreibung
docs.listADRs(projectId) Architecture Decision Records auflisten
docs.createADR(projectId, data) Einen ADR erstellen
docs.listReleases(projectId) Releases auflisten
docs.createRelease(projectId, data) Ein Release erstellen
docs.listChangeRequests(projectId) Change Requests auflisten
docs.createChangeRequest(projectId, data) Einen Change Request erstellen

Fehlerbehandlung

Beide SDKs werfen typisierte Fehler mit dem HTTP-Statuscode und den Fehlerdetails aus der 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"

Häufige Statuscodes:

Code Bedeutung
400 Bad Request - Ungültige Parameter
401 Unauthorized - Ungültiger oder fehlender API-Schlüssel
403 Forbidden - Unzureichende Berechtigungen
404 Not Found - Ressource existiert nicht
429 Too Many Requests - Rate-Limit überschritten
500 Internal Server Error

Konfiguration

Eigene Basis-URL

Übergeben Sie für selbst gehostete Archyl-Instanzen eine eigene baseUrl:

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",
)

Quellcode

Beide SDKs sind Open Source:

Nächste Schritte