Panoramica API

Archyl fornisce un'API completa che ti permette di integrare la documentazione architetturale nei tuoi flussi di lavoro, strumenti e pipeline di automazione.

Endpoint API

Archyl offre due interfacce API:

API REST

L'API REST fornisce accesso completo a tutte le funzionalità di Archyl:

• Creare e gestire progetti
• Aggiungere, aggiornare ed eliminare elementi architetturali
• Gestire le relazioni
• Gestire ADR e documentazione
• Esportare diagrammi

URL Base: https://api.archyl.com/api/v1

Server MCP

Il server Model Context Protocol (MCP) consente agli assistenti AI di interagire con la tua architettura:

• Claude Code, Claude Desktop
• Cursor
• VS Code con Copilot
• Altri strumenti compatibili con MCP

Endpoint SSE: https://api.archyl.com/sse Endpoint HTTP: https://api.archyl.com/mcp

Autenticazione

Tutte le richieste API richiedono l'autenticazione tramite una chiave API:

curl -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

Creazione Chiavi API

1. Vai su Profilo → Chiavi API
2. Clicca su "Crea Chiave API"
3. Scegli i permessi (sola lettura o lettura-scrittura)
4. Copia e conserva la chiave in modo sicuro

Permessi delle Chiavi

Guida Rapida

Elenco dei Tuoi Progetti

curl -X GET \
  -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

Creare un Sistema

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce Platform",
    "description": "Main e-commerce system",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

Creare una Relazione

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "system-1",
    "targetId": "system-2",
    "label": "Sends orders to",
    "technology": "REST/HTTPS"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/relationships

Gestione degli Errori

Gli errori API restituiscono codici di stato HTTP standard:

Le risposte di errore includono dettagli:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Name is required",
    "field": "name"
  }
}

SDK e Librerie

In arrivo:

• SDK JavaScript/TypeScript
• SDK Python
• SDK Go

Casi d'Uso

Integrazione CI/CD

Aggiorna automaticamente l'architettura dopo i deploy:

- name: Update Architecture
  run: |
    curl -X POST \
      -H "X-API-Key: ${{ secrets.ARCHYL_API_KEY }}" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

Strumenti Personalizzati

Costruisci strumenti interni che interagiscono con la tua architettura:

• Validazione architetturale
• Verifica di conformità
• Generazione di documentazione

Assistenti AI

Usa MCP per permettere agli assistenti AI di comprendere e aggiornare la tua architettura:

• Fare domande sulla tua architettura
• Creare elementi tramite linguaggio naturale
• Generare documentazione automaticamente

Documentazione API

La documentazione API interattiva completa è disponibile su:

https://api.archyl.com/docs

Questa documentazione OpenAPI include:

• Tutti gli endpoint disponibili
• Schemi di richiesta/risposta
• Funzionalità di prova
• Esempi di autenticazione

Prossimi Passi

• Autenticazione - Guida dettagliata all'autenticazione
• Server MCP - Configurare l'integrazione con assistenti AI