SDK

Archyl은 Node.js와 Python용 공식 SDK를 제공합니다. 두 SDK 모두 REST API를 감싼 가벼운 래퍼로, 인증, 직렬화, 오류 처리를 대신 처리해 줍니다.

설치

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

빠른 시작

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 레퍼런스

프로젝트

메서드 설명
projects.list() 조직의 모든 프로젝트 목록 조회
projects.get(projectId) ID로 프로젝트 조회
projects.create(data) 새 프로젝트 생성
projects.getC4Model(projectId) 프로젝트의 전체 C4 모델 조회
projects.getAgentContext(projectId) 아키텍처 컨텍스트(규칙, 기술 레이더, 결정) 조회

C4 모델

메서드 설명
c4.createSystem(projectId, data) 시스템 생성
c4.updateSystem(projectId, systemId, data) 시스템 수정
c4.createContainer(projectId, systemId, data) 컨테이너 생성
c4.updateContainer(projectId, containerId, data) 컨테이너 수정
c4.createComponent(projectId, containerId, data) 컴포넌트 생성
c4.createRelationship(projectId, data) 요소 간 관계 생성
c4.listRelationships(projectId) 모든 관계 목록 조회

거버넌스

메서드 설명
governance.runConformanceCheck(projectId, data) 파일에 대해 적합성 규칙 실행
governance.getReport(checkId) 검사의 전체 보고서 조회
governance.listRules() 모든 적합성 규칙 목록 조회
governance.createRule(data) 적합성 규칙 생성
governance.getStats(projectId?) 적합성 통계 조회
governance.computeDrift(projectId) 프로젝트의 드리프트 점수 계산
governance.getDriftScore(projectId) 최신 드리프트 점수 조회
governance.getDriftHistory(projectId) 시간에 따른 드리프트 점수 이력 조회

DORA 메트릭

메서드 설명
dora.getMetrics(projectId) 현재 DORA 메트릭 조회
dora.getTrend(projectId) 시간에 따른 DORA 메트릭 추세 조회

문서

메서드 설명
docs.listADRs(projectId) Architecture Decision Records 목록 조회
docs.createADR(projectId, data) ADR 생성
docs.listReleases(projectId) 릴리스 목록 조회
docs.createRelease(projectId, data) 릴리스 생성
docs.listChangeRequests(projectId) 변경 요청 목록 조회
docs.createChangeRequest(projectId, data) 변경 요청 생성

오류 처리

두 SDK 모두 API가 반환한 HTTP 상태 코드와 오류 세부 정보를 담은 타입이 지정된 오류를 던집니다.

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"

주요 상태 코드:

코드 의미
400 Bad Request - 잘못된 파라미터
401 Unauthorized - 유효하지 않거나 누락된 API 키
403 Forbidden - 권한 부족
404 Not Found - 리소스가 존재하지 않음
429 Too Many Requests - 속도 제한 초과
500 Internal Server Error

구성

사용자 지정 기본 URL

셀프 호스팅 Archyl 인스턴스에서는 사용자 지정 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",
)

소스 코드

두 SDK 모두 오픈 소스입니다:

다음 단계