SDK

Archyl fornisce SDK ufficiali per Node.js e Python. Entrambi sono wrapper leggeri attorno all'API REST che gestiscono per te autenticazione, serializzazione e gestione degli errori.

Installazione

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

Avvio rapido

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

Riferimento API

Progetti

Metodo Descrizione
projects.list() Elenca tutti i progetti dell'organizzazione
projects.get(projectId) Recupera un progetto tramite ID
projects.create(data) Crea un nuovo progetto
projects.getC4Model(projectId) Recupera il modello C4 completo di un progetto
projects.getAgentContext(projectId) Recupera il contesto architetturale (regole, tech radar, decisioni)

Modello C4

Metodo Descrizione
c4.createSystem(projectId, data) Crea un sistema
c4.updateSystem(projectId, systemId, data) Aggiorna un sistema
c4.createContainer(projectId, systemId, data) Crea un container
c4.updateContainer(projectId, containerId, data) Aggiorna un container
c4.createComponent(projectId, containerId, data) Crea un componente
c4.createRelationship(projectId, data) Crea una relazione tra elementi
c4.listRelationships(projectId) Elenca tutte le relazioni

Governance

Metodo Descrizione
governance.runConformanceCheck(projectId, data) Esegue le regole di conformità sui file
governance.getReport(checkId) Recupera il report completo di un controllo
governance.listRules() Elenca tutte le regole di conformità
governance.createRule(data) Crea una regola di conformità
governance.getStats(projectId?) Recupera le statistiche di conformità
governance.computeDrift(projectId) Calcola il punteggio di drift di un progetto
governance.getDriftScore(projectId) Recupera l'ultimo punteggio di drift
governance.getDriftHistory(projectId) Recupera l'andamento del punteggio di drift nel tempo

Metriche DORA

Metodo Descrizione
dora.getMetrics(projectId) Recupera le metriche DORA attuali
dora.getTrend(projectId) Recupera l'andamento delle metriche DORA nel tempo

Documentazione

Metodo Descrizione
docs.listADRs(projectId) Elenca gli Architecture Decision Record
docs.createADR(projectId, data) Crea un ADR
docs.listReleases(projectId) Elenca le release
docs.createRelease(projectId, data) Crea una release
docs.listChangeRequests(projectId) Elenca le richieste di modifica
docs.createChangeRequest(projectId, data) Crea una richiesta di modifica

Gestione degli errori

Entrambi gli SDK sollevano errori tipizzati con il codice di stato HTTP e i dettagli dell'errore restituiti dall'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"

Codici di stato comuni:

Codice Significato
400 Bad Request - Parametri non validi
401 Unauthorized - Chiave API non valida o mancante
403 Forbidden - Permessi insufficienti
404 Not Found - La risorsa non esiste
429 Too Many Requests - Limite di richieste superato
500 Internal Server Error

Configurazione

URL di base personalizzato

Per le istanze self-hosted di Archyl, passa un baseUrl personalizzato:

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

Codice sorgente

Entrambi gli SDK sono open source:

Prossimi passi