2단계 - API 인터페이스 (센서 네트워크 API)

API 표준 개요

애플리케이션 프로그래밍 인터페이스(API)는 현대 모니터링 시스템을 서로 잇는 결합 조직이다. WIA 표준의 2단계는 생태계 데이터에 대한 프로그래밍 방식 접근을 가능하게 하는 포괄적인 API 명세를 정의하며, 자동화된 워크플로, 실시간 대시보드, 분석 파이프라인, 시스템 통합을 지원한다. 1단계가 데이터 형식을 표준화한다면, 2단계는 그 데이터에 접근하고 질의하고 전송하는 방식을 표준화한다.

WIA API 표준은 단순성과 폭넓은 호환성을 위해 RESTful 설계 원칙을 채택하는 한편, 센서 네트워크를 위한 실시간 스트리밍 기능을 추가한다. 이러한 혼합 방식은 연구에서 흔히 쓰이는 일괄(batch) 데이터 접근 패턴과, 운영 모니터링에 필수적인 연속 데이터 스트림을 모두 지원한다.

RESTful API 아키텍처

WIA REST API는 업계 표준 HTTP 메서드와 상태 코드를 따르므로 개발자에게 곧바로 익숙하면서도, 모니터링에 특화된 기능을 제공한다.

핵심 엔드포인트

질의 매개변수

모든 엔드포인트의 기준 URL은 https://api.{domain}/v1/ 형태이다. 2단계 명세가 GET /observations에 대해 정의한 질의 매개변수는 다음과 같다.

• 분류군: taxon(학명)
• 기간: start_date, end_date(ISO 8601)
• 공간: bbox, "minLon,minLat,maxLon,maxLat" 순서의 문자열
• 페이지 나누기: limit(기본값 100, 최대 1000), offset
• 형식: format("json", "csv", "geojson")

센서 시계열 엔드포인트 GET /sensors/{id}/data는 start_time, end_time, aggregation("raw", "hourly", "daily", "monthly"), format("json", "csv", "netcdf")을 받는다. 반경 검색, 정렬, 품질 하한(quality_min) 같은 추가 필터는 구현이 선택적으로 제공할 수 있는 확장이며, 명세의 기본 매개변수와 이름이 겹치지 않게 정의하고 OpenAPI 문서에 명시해야 한다.

API 요청 예시

GET /api/v1/observations?
    taxon=Haliaeetus+leucocephalus&
    start_date=2025-01-01&
    end_date=2025-12-31&
    bbox=-123.0,47.0,-122.0,48.0&
    quality_min=0.8&
    limit=100&
    format=json

Authorization: Bearer YOUR_API_KEY
Accept: application/json

응답 형식

모든 API 응답은 메타데이터, 데이터, 페이지 정보를 담은 일관된 구조를 따른다.

{
  "status": "success",
  "api_version": "1.0",
  "request_id": "req-12345",
  "timestamp": "2025-12-26T15:30:00Z",
  "query": {
    "taxon": "Haliaeetus leucocephalus",
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "bbox": "-123.0,47.0,-122.0,48.0"
  },
  "pagination": {
    "total_records": 342,
    "returned_records": 100,
    "page": 1,
    "total_pages": 4,
    "next_page": "/api/v1/observations?page=2&..."
  },
  "data": [
    {
      "record_id": "OBS-2025-001",
      "timestamp": "2025-03-15T10:30:00Z",
      "taxon": {...},
      "location": {...},
      ...
    },
    ...
  ]
}

인증과 권한 부여

생태계 모니터링 데이터에서 보안은 무엇보다 중요하다. 민감한 종의 위치를 보호하면서도 적절한 접근은 허용해야 하기 때문이다. WIA는 여러 인증 방식을 지원한다.

API 키

요청 헤더에 API 키를 담아 전달하는 단순한 인증 방식이다: Authorization: Bearer YOUR_API_KEY. 서버 간 통신과 스크립트 기반 접근에 적합하다.

OAuth 2.0

사용자 인증, 범위가 지정된 권한, 토큰 갱신을 지원하는 업계 표준 권한 부여 프레임워크이다. 세분화된 접근 제어가 필요한 웹 애플리케이션과 서비스에 적합하다.

JWT 토큰

JSON 웹 토큰(JWT)은 사용자 신원과 권한에 관한 클레임을 토큰 안에 담아 무상태(stateless) 인증을 가능하게 한다. 분산 시스템과 마이크로서비스 아키텍처에 유용하다.

접근 제어

2단계 명세는 인증 방식만 규정하고 접근 등급 체계는 구현에 맡긴다. 실무에서는 세분화된 권한을 통해 사용자가 접근하고 수정할 수 있는 데이터를 제어하며, 다음과 같은 등급 구성이 흔히 쓰인다.

• 공개(Public): 인증 없이 누구나 접근할 수 있는 데이터
• 등록 사용자(Registered): 인증이 필요하지만 모든 등록 사용자가 이용할 수 있는 데이터
• 그룹(Group): 특정 사용자 그룹이나 기관으로 제한되는 데이터
• 비공개(Private): 데이터 소유자와 명시적으로 권한을 받은 사용자만 이용할 수 있는 데이터
• 엠바고(Embargoed): 공개 일정이 정해진 채 일시적으로 제한되는 데이터

실시간 스트리밍 API

센서 네트워크는 연속적인 데이터 스트림을 생성하므로 일괄 질의와는 다른 접근 패턴이 필요하다. WIA는 WebSocket과 MQTT 프로토콜을 사용하는 실시간 스트리밍 API를 제공한다.

WebSocket 연결

WebSocket은 양방향 통신 채널을 제공하여 서버에서 클라이언트로 데이터를 실시간으로 푸시할 수 있게 한다. 애플리케이션은 지속 연결을 수립하고, 센서 업데이트가 발생하는 즉시 이를 수신한다.

// 클라이언트 측 JavaScript 예시
const ws = new WebSocket('wss://api.example.org/stream');

ws.onopen = () => {
  // 특정 센서 구독
  ws.send(JSON.stringify({
    action: 'subscribe',
    sensors: ['TEMP-001', 'TEMP-002'],
    filters: {
      quality_min: 0.8
    }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('새 센서 측정값:', data);
  updateDashboard(data);
};

IoT 기기를 위한 MQTT

MQTT(Message Queuing Telemetry Transport)는 대역폭과 전력이 제한된 IoT 기기에 적합한 경량 발행-구독(publish-subscribe) 프로토콜이다. 센서는 토픽에 데이터를 발행하고, 구독자는 업데이트를 수신한다.

# 토픽 구조
sensors/{sensor_id}/data
sensors/{sensor_id}/status
sensors/{sensor_id}/alerts

# MQTT 발행 예시
Topic: sensors/TEMP-001/data
Payload: {
  "timestamp": "2025-12-26T15:30:00Z",
  "value": 12.3,
  "unit": "celsius",
  "qc_flag": "good"
}

# 종 관찰 토픽
observations/{site_id}/species

QoS 수준은 0(최대 한 번), 1(최소 한 번), 2(정확히 한 번)를 쓴다. 명세는 일반 데이터에는 QoS 1을, 중요 경보에는 QoS 2를 권장한다. WebSocket 데이터 메시지도 같은 형태로 "type": "sensor_reading", sensor_id, timestamp, value, unit, qc_flag를 담는다.

대량 데이터 접근

대규모 분석에는 개별 API 질의를 넘어서는 효율적인 대량 데이터 접근이 필요하다. WIA는 여러 가지 대량 접근 패턴을 지원한다.

비동기 질의

결과 집합이 큰 질의의 경우, 클라이언트가 요청을 제출하면 비동기로 처리된다. API는 작업 ID를 반환하며, 클라이언트는 완료 여부를 주기적으로 확인(폴링)하다가 준비되면 결과를 내려받는다.

POST /api/v1/bulk-query
{
  "query": {
    "dataset": "all-observations",
    "start_date": "2020-01-01",
    "end_date": "2025-12-31",
    "format": "csv"
  }
}

Response:
{
  "job_id": "bulk-123",
  "status": "queued",
  "estimated_time": "300 seconds",
  "status_url": "/api/v1/jobs/bulk-123"
}

# 상태 확인
GET /api/v1/jobs/bulk-123

# 준비되면 내려받기
GET /api/v1/jobs/bulk-123/download

데이터 덤프

질의 없이 내려받을 수 있도록 미리 생성해 둔 데이터셋이 /dumps/ 경로에 제공된다.

파일 형식과 크기는 운영 기관과 보유 데이터에 따라 달라지므로 명세가 고정하지 않는다. 다중 레코드 파일은 제4장의 파일 형식 규약(NDJSON, gzip 압축 권장)을 따르는 것이 좋다.

데이터 제출 API

WIA API는 데이터 조회뿐 아니라 데이터 제출도 지원하여, 기여자가 관찰 기록과 센서 데이터를 업로드할 수 있게 한다.

단일 관찰 기록 제출

POST /api/v1/observations
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "wia_version": "1.0",
  "schema_type": "species-observation",
  "timestamp": "2025-12-26T14:00:00Z",
  "taxon": {...},
  "location": {...},
  ...
}

Response (201 Created):
{
  "status": "success",
  "record_id": "OBS-2025-12345",
  "validation": {
    "passed": true,
    "quality_score": 0.95
  }
}

일괄 제출

효율을 위해 여러 관찰 기록을 한 번에 제출한다. 명세에서 POST /observations는 단일 객체와 배열을 모두 받으므로, 별도의 일괄 제출 엔드포인트 없이 같은 엔드포인트에 레코드 배열을 보낸다. 응답에는 생성된 ID와 레코드별 검증 결과가 담긴다. 한 번에 보내는 레코드 수는 제4장의 권장 한도(파일당 10,000건)를 넘지 않는 것이 좋다.

POST /api/v1/observations
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

[
  {...관찰 기록 1...},
  {...관찰 기록 2...},
  {...관찰 기록 3...}
]

Response:
{
  "status": "success",
  "submitted": 3,
  "accepted": 3,
  "rejected": 0,
  "results": [
    {"record_id": "OBS-001", "status": "accepted"},
    {"record_id": "OBS-002", "status": "accepted"},
    {"record_id": "OBS-003", "status": "accepted"}
  ]
}

오류 처리

명확한 메시지를 갖춘 견고한 오류 처리는 개발자가 문제를 진단하고 해결하는 데 도움이 된다. 오류 응답은 다음과 같은 공통 구조를 따른다.

{
  "status": "error",
  "error_code": "INVALID_PARAMETER",
  "message": "사람이 읽을 수 있는 오류 설명",
  "details": { },
  "request_id": "req-12345",
  "timestamp": "2025-12-26T15:30:00Z"
}

명세가 사용하는 HTTP 상태 코드는 다음과 같다.

요청 한도 제한

공정 사용 정책은 남용을 막으면서 서비스 가용성을 보장한다.

• 익명 사용자: 시간당 100회 요청
• 인증된 사용자: 시간당 1,000회 요청
• 프리미엄/연구 계정: 시간당 10,000회 요청

요청 한도 헤더는 클라이언트에게 현재 상태를 알려 준다.

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

API 버전 관리

API는 시간이 지나며 발전한다. WIA는 URL 기반 버전 관리를 사용하여 하위 호환성을 보장하면서도 혁신을 가능하게 한다.

https://api.example.org/v1/observations
https://api.example.org/v2/observations

지원 중단(deprecation)이 결정된 버전도 최소 12개월 동안 계속 지원한다. 이 기간에 클라이언트는 새 버전으로 이전할 수 있다.

문서화와 개발자 도구

포괄적인 문서와 도구는 통합을 가속한다.

OpenAPI 명세

기계가 읽을 수 있는 API 명세는 도구의 자동 생성을 가능하게 한다. WIA 구현은 완전한 OpenAPI 3.0 명세를 https://api.{domain}/openapi.json에 게시하며, 여기에 엔드포인트 문서, 요청/응답 예시, 검증 스키마가 담긴다.

SDK와 클라이언트 라이브러리

2단계 명세(§6)는 공식 클라이언트 라이브러리의 패키지 이름을 다음과 같이 지정한다. 이 판 기준으로 아직 공개되지 않았으므로, 그 전까지는 REST API를 직접 호출하거나 저장소 api/typescript 디렉터리의 참조 TypeScript SDK 소스에서 출발한다.

• JavaScript/TypeScript: npm 패키지 @wia/ecosystem-monitoring
• Python: pip 패키지 wia-ecosystem-monitoring
• R: CRAN 패키지 wiaR
• Java: Maven 아티팩트 org.wia:ecosystem-monitoring

대화형 문서

웹 기반 API 탐색기를 사용하면 코드를 작성하지 않고도 브라우저에서 직접 엔드포인트를 시험할 수 있다. 개발자는 질의를 실험하고, 응답을 확인하고, 코드 예시를 생성할 수 있다.