통합 가이드

Supplier가 자기 백엔드(BFF, Backend-for-Frontend)에서 LinkOStar를 호출해 자기 end-user 화면에 데이터를 그리는 가장 일반적인 흐름을 정리합니다. LinkOStar는 raw resource API만 제공하고, 화면용 cross-resource 집계는 통합 측 책임이라는 원칙을 따릅니다.

1. 통합 패턴 (BFF + Proxy)

Supplier admin UI 또는 mobile app이 LinkOStar를 직접 부르지 않고, 중간에 Supplier의 BFF를 둡니다. BFF는 다음 두 역할을 합니다.

인증 변환: end-user의 supplier-side 세션을 받아서 LinkOStar의 X-API-Key로 치환.
집계: 여러 LinkOStar endpoint 결과를 묶어서 화면용 응답으로 만듦.

Supplier UI ──(supplier session)──▶ Supplier BFF ──(X-API-Key + X-Tenant-UUID)──▶ LinkOStar
                                       │
                                       └── 집계/캐시/권한 검사

2. 호출하기 전에 필요한 것

X-API-Key: supplier 단위로 발급되는 시크릿. 인증 참조.
X-Tenant-UUID: 어떤 tenant scope로 동작할지 알리는 헤더. supplier당 1개.
base URL: https://api.linkostar.sandevaux.com (production).

3. 자주 호출되는 endpoint 카테고리

전체 목록은 API Reference에서. 카테고리 단위로:

카테고리	대표 endpoint	용도
Hubs	`GET /tenant/hubs`	tenant 소속 hub 목록·페이지네이션
Devices	`GET /tenant/devices`	hub에 연결된 device 목록
Hub Monitoring	`GET /tenant/hub-monitoring/{hubUuid}/telemetry`	특정 hub의 텔레메트리 시계열
Provisioning Steps	`GET /tenant/provisioning-steps`	supplier가 정의한 onboarding step 정의
Hub Provisioning Run	`GET /tenant/hubs/{hubUuid}/provisioning/steps`	특정 hub에 적용된 step의 진행 상태
Supplier Bundles	`POST /tenant/supplier-bundles`	출시 패키지 CRUD
Data Pipelines	`POST /tenant/data-pipelines`	텔레메트리 변환·전달 규칙
Consent	`POST /tenant/consent-settings`	end-user 동의 흐름 설정

4. 4-카드 대시보드를 만드는 예시

Supplier admin 화면에 hub 수 / device 수 / 활성 알림 / 시스템 상태 4개 카드를 그린다고 가정합니다. LinkOStar 측엔 /dashboard/stats가 의도적으로 없습니다 — 이런 cross-resource 집계는 supplier BFF 의 책임입니다. BFF에서:

// Supplier BFF (Java 예시)
long hubCount    = totalElementsFromList("tenant/hubs");
long deviceCount = totalElementsFromList("tenant/devices");
return new DashboardStatsResponse(hubCount, deviceCount, activeAlerts, systemStatus);

private long totalElementsFromList(String path) {
    Map<String,Object> resp = linkostar.get(path + "?page=1&size=1");
    return ((Number) ((Map<?,?>) resp.get("pagination")).get("totalElements")).longValue();
}

page=1&size=1로 호출해 pagination.totalElements만 뽑는 패턴이 가장 가볍습니다. 응답 규약 참조.

5. SDK 자동 생성

Live OpenAPI spec (/api-docs) 으로 SDK 클래스를 자동 생성해 두면 breaking change를 컴파일러가 잡습니다. CI에서 daily fetch + diff 권장.

# Java
openapi-generator-cli generate \
    -i https://api.linkostar.sandevaux.com/api-docs \
    -g java -o ./generated-linkostar-client \
    --additional-properties=library=resttemplate

# TypeScript
openapi-generator-cli generate \
    -i https://api.linkostar.sandevaux.com/api-docs \
    -g typescript-fetch -o ./generated-linkostar-client

6. 모범 사례 / 안티 패턴

✅ BFF에서 envelope unwrap 후 supplier UI에는 평탄화한 객체만 노출.
✅ LinkOStar 호출 실패는 BFF에서 graceful fallback — 단일 resource 장애가 화면 전체를 500 시키지 않게.
✅ OpenAPI 클라이언트 자동 생성 + CI에서 spec diff 알림.
❌ End-user 브라우저에서 LinkOStar 직호출 금지 — X-API-Key가 노출됨.
❌ LinkOStar에 supplier-specific 집계 endpoint 요청 금지 — supplier BFF에서 만드세요.
❌ 응답 envelope 가정 깨지 않기 — list endpoint는 늘 {data, pagination}, single은 {data}.

7. Sandbox / 로컬 개발

Production: https://api.linkostar.sandevaux.com.
Local: http://localhost:8080 (LinkOStar backend 레포의 ./mvnw spring-boot:run).
Staging 환경 별도 부재 (필요한 경우 LinkOStar 운영팀에 문의).