2단계 - API 인터페이스

데이터에서 시스템 통합으로

1단계 데이터 형식은 어떤 정보를 교환해야 하는지를 정한다. 2단계 API 사양은 시스템들이 그 정보를 어떻게 교환하는지를 정의한다. 표준화된 API가 없으면 조직은 협력사마다 맞춤형 연동을 개발해야 하며, 네트워크가 커질수록 복잡도가 기하급수적으로 늘어난다. 재활용 시설 열 곳과 거래하는 수거업체라면 서로 다른 연동 방식 열 가지가 필요하다. 여러 수거·처리 조직을 거치는 제품을 추적하는 제조업체도 비슷한 복잡도 증가에 직면한다.

RESTful API는 모든 당사자가 구현하는 균일한 인터페이스를 제공함으로써 이 문제를 해결한다. 시스템이 일단 WIA 전자폐기물 관리 API를 지원하면, 맞춤 개발 없이도 다른 모든 준수 시스템과 연동할 수 있다. 이러한 상호 운용성은 연동 비용을 획기적으로 줄이는 동시에, 대규모의 효과적인 전자폐기물 관리에 필요한 네트워크 차원의 조정을 가능하게 한다.

REST 아키텍처 원칙

WIA API는 REST(Representational State Transfer) 아키텍처 원칙을 따르며, HTTP 메서드와 상태 코드를 활용하여 명확하고 예측 가능한 상호작용을 구현한다. RESTful 설계는 전자폐기물 관리에 다음과 같은 여러 이점을 제공한다.

• 단순성: 익숙한 HTTP 프로토콜을 사용하여 구현 장벽을 낮춘다
• 무상태성: 각 요청이 필요한 모든 정보를 담고 있어 신뢰성이 향상된다
• 캐시 가능성: 응답을 캐시할 수 있어 부하가 줄고 성능이 향상된다
• 확장성: 무상태 설계와 캐싱으로 수평 확장이 가능하다
• 언어 독립성: HTTP를 지원하는 모든 언어로 API를 구현할 수 있다

HTTP 메서드의 의미

API는 표준 HTTP 메서드를 일관된 의미로 사용한다.

핵심 API 엔드포인트

이 표준은 기기 관리, 폐기물 추적, 수거 운영, 처리 문서화, 자재 회수, 규정 준수 보고를 포괄하는 엔드포인트 범주를 정의한다. 각 범주는 관련 작업을 공통 경로 접두사 아래에 묶는다.

기기 관리 API

기기 등록과 정보 조회는 추적 시스템의 토대이다. 이 엔드포인트를 통해 제조업체는 제품을 등록하고, 권한이 있는 당사자는 정보를 조회하며, 시스템은 생애주기 전반에 걸쳐 기기 상태를 갱신한다.

POST /api/v1/devices
제조업체 선언과 함께 신규 기기 등록
요청 본문: 1단계 스키마에 따른 Device 객체
응답: 201 Created, device_id 및 QR 코드 URL 포함

GET /api/v1/devices/{device_id}
기기 정보 전체 조회
응답: 200 OK, 이력을 포함한 전체 device 객체

GET /api/v1/devices?manufacturer={mfr}&model={model}
조건별 기기 질의
응답: 200 OK, 조건에 맞는 기기 배열

PATCH /api/v1/devices/{device_id}/status
기기 생애주기 상태 갱신
요청 본문: {"status": "collected", "timestamp": "..."}
응답: 200 OK, 갱신된 device 객체

GET /api/v1/devices/{device_id}/materials
재료 구성 선언 조회
응답: 200 OK, 1단계 스키마에 따른 자재 명세서(BOM)

수거 및 추적 API

기기가 재활용 흐름에 들어오면 수거 이벤트를 기록해야 한다. 이 엔드포인트는 소매점 회수, 지자체 거점 배출, 기업 ITAD, 전문 유해폐기물 수거 등 다양한 수거 방식을 지원한다.

POST /api/v1/collections
새 수거 이벤트 생성
요청 본문: {
  "device_ids": ["uuid1", "uuid2", ...],
  "collection_method": "retail_takeback",
  "collector_id": "COL-12345",
  "location": {...},
  "timestamp": "2025-11-08T10:30:00Z",
  "condition_assessments": [...]
}
응답: 201 Created, collection_id 포함

GET /api/v1/collections/{collection_id}
수거 이벤트 상세 조회
응답: 200 OK, collection 객체

GET /api/v1/collections?facility={fac_id}&date_range={range}
조건별 수거 기록 질의
응답: 200 OK, collection 배열

POST /api/v1/collections/{collection_id}/devices
기존 수거 배치에 기기 추가
요청 본문: {"device_ids": ["uuid3", "uuid4"]}
응답: 200 OK, 갱신된 collection

처리 및 회수 API

처리 시설은 재활용 작업의 각 단계를 문서화한다. 이 엔드포인트는 해체, 파쇄, 선별, 정련, 자재 회수 활동을 기록하여 완전한 처리 감사 추적을 만든다.

POST /api/v1/processing/stages
처리 단계 완료 문서화
요청 본문: {
  "stage_type": "dismantling",
  "input_devices": ["uuid1", "uuid2", ...],
  "facility_id": "RC-US-CA-001",
  "timestamp": "2025-11-10T14:00:00Z",
  "outputs": [
    {
      "component_type": "battery",
      "quantity": 250,
      "total_weight_kg": 3.2,
      "disposition": "battery_recycler"
    }
  ]
}
응답: 201 Created, stage_id 포함

POST /api/v1/recovery/materials
자재 회수 결과 보고
요청 본문: {
  "source_devices": ["uuid1", "uuid2", ...],
  "facility_id": "RC-US-CA-001",
  "recovery_date": "2025-11-15",
  "recovered_materials": [
    {
      "material": "Copper",
      "cas_number": "7440-50-8",
      "weight_kg": 12.5,
      "purity_percentage": 95.2,
      "destination_facility": "SM-US-PA-001"
    }
  ]
}
응답: 201 Created, recovery_report_id 포함

GET /api/v1/recovery/reports/{report_id}
회수 보고서 조회
응답: 200 OK, 전체 회수 문서

인증과 권한 부여

전자폐기물 데이터에는 상업적으로 민감한 정보, 개인정보, 규정 준수 문서가 포함되어 있어 접근 통제가 필요하다. API는 인증에 OAuth 2.0을, 권한 부여에 역할 기반 접근 제어(RBAC)를 사용한다.

OAuth 2.0 구현

이 표준은 다양한 연동 시나리오에 대응하기 위해 여러 OAuth 2.0 흐름을 지원한다.

• 클라이언트 자격 증명(Client Credentials): 서버 간 연동(재활용업체 시스템과 제조업체 시스템 간)
• 인가 코드(Authorization Code): 사용자 위임 접근(소비자가 자신의 기기를 추적)
• 리프레시 토큰(Refresh Token): 반복 인증 없이 유지되는 장기 세션

POST /api/v1/oauth/token
액세스 토큰 요청
요청 본문: {
  "grant_type": "client_credentials",
  "client_id": "recycler_12345",
  "client_secret": "secret_xyz...",
  "scope": "devices:read collections:write"
}
응답: {
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "devices:read collections:write"
}

사용 예:
GET /api/v1/devices/abc-123
Authorization: Bearer eyJhbG...

역할 기반 접근 제어

이 표준은 이해관계자 역할과 그에 따른 권한을 다음과 같이 정의한다.

요청 속도 제한과 성능

API 구현은 남용을 막으면서 다양한 부하 수준을 처리해야 한다. 이 표준은 안정적인 서비스를 보장하기 위해 요청 속도 제한 정책과 성능 기대치를 규정한다.

요청 속도 제한 정책

요청 한도는 서비스 등급에 따라 표준(standard) 등급은 시간당 1,000건, 엔터프라이즈(enterprise) 등급은 시간당 10,000건이다. 한도 정보는 HTTP 헤더로 전달되며, 한도를 넘으면 HTTP 429를 반환한다.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1731072000

HTTP 429 Too Many Requests
한도 초과 시 응답:
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 1000 requests/hour exceeded",
  "retry_after": 1847
}

성능 기대치

이 표준은 API 구현에 대해 다음과 같은 성능 목표를 규정한다.

• 응답 시간: 단순 질의의 95번째 백분위수 < 500ms
• 가용성: 가동률 99.5%(계획된 유지보수 제외)
• 처리량: 시설당 초당 100건 요청 지원

오류 처리와 상태 코드

일관된 오류 응답은 클라이언트가 실패를 원활하게 처리할 수 있게 한다. API는 표준 HTTP 상태 코드와 함께 상세 정보를 담은 구조화된 오류 본문을 사용한다.

HTTP 400 Bad Request
{
  "error": "validation_error",
  "message": "Request body failed schema validation",
  "details": [
    {
      "field": "device.weight_kg",
      "error": "must be positive number",
      "value": -0.5
    },
    {
      "field": "device.weee_category",
      "error": "must be one of WEEE-1 through WEEE-6",
      "value": "WEEE-7"
    }
  ]
}

버전 관리 전략

API는 기존 연동과의 하위 호환성을 유지하면서 발전해야 한다. 이 표준은 명확한 지원 중단 정책과 함께 URL 기반 버전 관리를 채택한다.

버전 생애주기

API 버전은 다음과 같은 체계적인 생애주기를 따른다.

• 현행(Current): 최신 버전, 모든 신규 기능, 전면 지원
• 지원(Supported): 직전 버전, 보안 업데이트, 2년 지원 보장
• 지원 중단 예정(Deprecated): 구버전, 보안 업데이트만 제공, 종료 6개월 전 사전 고지
• 폐기(Retired): 더 이상 접근 불가, 클라이언트는 업그레이드해야 함

/api/v1/devices  - 현행 버전 (v1.0)
/api/v2/devices  - 향후 버전 (개발 중)

응답 헤더의 버전 정보:
X-API-Version: 1.0.0
X-API-Deprecated: false
X-API-Sunset-Date: null

웹훅 알림

실시간 연동을 위해 API는 폴링 없이 구독자에게 이벤트를 알리는 웹훅을 지원한다. 조직은 웹훅 엔드포인트를 등록하여 기기 상태 변경, 수거 이벤트, 처리 완료에 관한 알림을 받는다.

POST /api/v1/webhooks
웹훅 엔드포인트 등록
요청 본문: {
  "url": "https://recycler.example.com/wia-webhook",
  "events": ["device.collected", "processing.complete"],
  "secret": "webhook_secret_xyz"
}
응답: 201 Created, webhook_id 포함

웹훅 전달(등록된 URL로 전송):
POST https://recycler.example.com/wia-webhook
X-WIA-Event: device.collected
X-WIA-Signature: sha256=abc123...
{
  "event_type": "device.collected",
  "event_id": "evt_xyz",
  "timestamp": "2025-11-08T10:30:00Z",
  "data": {
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "collection_id": "col_123",
    "collector_id": "COL-12345"
  }
}

규정 준수 보고 API

자동화된 규정 준수 보고는 행정 부담을 줄이는 동시에 데이터 품질을 높인다. 이 엔드포인트는 표준화된 추적 데이터로부터 다양한 규제 요건에 맞는 보고서를 생성한다.

GET /api/v1/compliance/reports/epr
생산자책임재활용(EPR) 보고서 생성
매개변수:
  - jurisdiction (EU, California, Japan 등)
  - period (2025-Q1, 2025-annual)
  - format (JSON, PDF, XML)
응답: 관할 지역별 EPR 보고서

GET /api/v1/compliance/reports/basel
바젤협약 문서 생성
매개변수:
  - shipment_id
  - export_country
  - import_country
응답: 사전통보동의(PIC) 문서

GET /api/v1/compliance/certificates/{device_id}
기기의 재활용 인증서 조회
응답: 회수 문서가 포함된 PDF 인증서