제5장

2단계 - API 인터페이스 사양

프로그래밍 방식 접근의 힘

1단계가 표준화된 데이터 형식을 확립했다면, 2단계는 시스템이 애플리케이션 프로그래밍 인터페이스(API)를 통해 그 데이터를 어떻게 제공하는지를 정의한다. API는 가뭄 모니터링을 수동 데이터 조회에서 자동화된 통합으로 전환하여 실시간 의사결정 지원, 경보 시스템, 그리고 농업 관리 도구와의 원활한 연결을 가능하게 한다.

WIA API 사양은 RESTful 설계 원칙을 따르므로 개발자에게 익숙하며, 동시에 시간 기반 쿼리, 공간 필터링, 경보 구독과 같은 가뭄 특화 요구사항을 반영한다.

핵심 API 설계 원칙

WIA 가뭄 모니터링 API는 다음과 같은 몇 가지 기본 원칙을 준수한다.

RESTful 아키텍처: URL로 식별되는 리소스, 표준 HTTP 메서드(GET, POST, PUT, DELETE)
상태 비저장 작업: 각 요청이 필요한 모든 정보를 포함한다
JSON 응답: 1단계 데이터 형식과 일관성을 유지한다
버전이 지정된 엔드포인트: 원활한 발전을 위해 URL 경로에 API 버전(/v1/, /v2/)을 포함한다
예측 가능한 오류 처리: 상세한 오류 메시지를 동반한 표준 HTTP 상태 코드
요청 속도 제한: 명확한 할당량 안내를 갖춘 공정 사용 정책
CORS 지원: 웹 애플리케이션을 위한 교차 출처 요청 허용

기본 URL 구조

WIA를 준수하는 모든 API는 일관된 URL 구조를 따른다.

https://{domain}/wia/drought/v1/{resource}

예시(도메인은 가상의 예):
https://api.drought-a.example.org/wia/drought/v1/pdsi
https://climate.example.org/wia/drought/v1/spi
https://data.example.gov/wia/drought/v1/soil-moisture

구성 요소	목적	예시
도메인	서비스 제공자	api.drought-a.example.org
/wia/drought	WIA 가뭄 표준 네임스페이스	모든 구현에서 고정
/v1	API 버전	v1, v2, v3 등
리소스	특정 데이터 엔드포인트	pdsi, spi, ndvi 등

인증 및 권한 부여

WIA 표준은 보안과 접근성 사이의 균형을 맞추기 위해 여러 인증 방식을 지원한다.

API 키 인증(모든 구현에 필수)

GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060
헤더:
  X-WIA-API-Key: your-api-key-here
  Accept: application/json

OAuth 2.0(선택 사항, 고급 구현용)

GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060
헤더:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  Accept: application/json

공개 접근(제한적)

교육 및 연구 목적으로 인증 없이 기본 데이터에 접근할 수 있다.

GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060&public=true

응답에는 요청 속도 제한 안내와 출처 표시 요구사항이 포함된다

접근 등급	인증	요청 속도 제한	기능
공개	없음	100 요청/일	기본 현재 데이터
등록	API 키	10,000 요청/일	과거 데이터, 경보
프리미엄	OAuth 2.0	100,000 요청/일	모든 기능, 우선 지원
연구/정부	OAuth 2.0	무제한	대량 다운로드, 스트리밍

현재 가뭄 상태 엔드포인트

위치별 PDSI 조회

GET /wia/drought/v1/pdsi

쿼리 매개변수:
  lat (필수): 위도 (-90 ~ 90)
  lon (필수): 경도 (-180 ~ 180)
  date (선택): ISO 8601 날짜, 기본값은 가장 최근 날짜

요청 예시:
GET /wia/drought/v1/pdsi?lat=40.7128&lon=-74.0060&date=2025-12-26

응답 예시:
{
  "wia_version": "1.0",
  "data_type": "pdsi",
  "timestamp": "2025-12-26T00:00:00Z",
  "location": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128],
    "properties": {
      "region": "Northeast US",
      "climate_division": "NJ-02"
    }
  },
  "pdsi": {
    "value": -2.5,
    "classification": "moderate_drought",
    "percentile": 15.3
  },
  "metadata": {
    "source_organization": "NOAA NCEI",
    "quality_flag": "good"
  }
}

위치 및 시간 척도별 SPI 조회

GET /wia/drought/v1/spi

쿼리 매개변수:
  lat (필수): 위도
  lon (필수): 경도
  scale (필수): 월 단위 시간 척도 (1, 3, 6, 12, 24)
  date (선택): ISO 8601 날짜

요청 예시:
GET /wia/drought/v1/spi?lat=36.7783&lon=-119.4179&scale=12

응답 예시:
{
  "wia_version": "1.0",
  "data_type": "spi",
  "timestamp": "2025-12-26T00:00:00Z",
  "location": {
    "type": "Point",
    "coordinates": [-119.4179, 36.7783]
  },
  "spi": {
    "value": -1.8,
    "time_scale_months": 12,
    "classification": "severely_dry",
    "percentile": 3.6
  }
}

토양 수분 데이터 조회

GET /wia/drought/v1/soil-moisture

쿼리 매개변수:
  lat (필수): 위도
  lon (필수): 경도
  depth (선택): cm 단위의 특정 깊이, 또는 모든 층의 경우 "all"
  date (선택): ISO 8601 날짜

요청 예시:
GET /wia/drought/v1/soil-moisture?lat=32.7767&lon=-96.7970&depth=all

NDVI 식생 데이터 조회

GET /wia/drought/v1/ndvi

쿼리 매개변수:
  bbox (필수): 경계 상자 [west,south,east,north]
  date (선택): ISO 8601 날짜
  resolution (선택): 미터 (250, 500, 1000)

요청 예시:
GET /wia/drought/v1/ndvi?bbox=-96.8050,32.7680,-96.7890,32.7850

응답 예시:
{
  "wia_version": "1.0",
  "data_type": "ndvi",
  "timestamp": "2025-12-20T10:30:00Z",
  "location": {
    "type": "Polygon",
    "coordinates": [[[-96.8050,32.7850],[-96.7890,32.7850],
                     [-96.7890,32.7680],[-96.8050,32.7680],
                     [-96.8050,32.7850]]]
  },
  "ndvi": {
    "value": 0.45,
    "anomaly": -0.15,
    "drought_indicators": {
      "vegetation_stress": "moderate"
    }
  }
}

과거 데이터 쿼리

추세 분석과 비교를 위해 가뭄 지수의 시계열에 접근한다.

시계열 엔드포인트

GET /wia/drought/v1/{index}/timeseries

쿼리 매개변수:
  lat (필수): 위도
  lon (필수): 경도
  start_date (필수): ISO 8601 날짜
  end_date (필수): ISO 8601 날짜
  interval (선택): daily, weekly, monthly (기본값: monthly)

요청 예시:
GET /wia/drought/v1/pdsi/timeseries?lat=40.7128&lon=-74.0060
    &start_date=2024-01-01&end_date=2025-12-26&interval=monthly

응답 예시:
{
  "wia_version": "1.0",
  "data_type": "pdsi_timeseries",
  "location": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128]
  },
  "time_series": [
    {
      "timestamp": "2024-01-01T00:00:00Z",
      "pdsi": {"value": 1.2, "classification": "slightly_wet"}
    },
    {
      "timestamp": "2024-02-01T00:00:00Z",
      "pdsi": {"value": 0.8, "classification": "near_normal"}
    },
    ...
    {
      "timestamp": "2025-12-01T00:00:00Z",
      "pdsi": {"value": -2.5, "classification": "moderate_drought"}
    }
  ],
  "statistics": {
    "count": 24,
    "mean": -0.45,
    "min": -2.8,
    "max": 1.5,
    "trend": "declining"
  }
}

공간 쿼리 엔드포인트

단일 지점이 아닌 지역 단위로 가뭄 데이터를 조회한다.

경계 상자 쿼리

GET /wia/drought/v1/{index}/bbox

쿼리 매개변수:
  bbox (필수): west,south,east,north (십진 도)
  date (선택): ISO 8601 날짜
  format (선택): geojson, json (기본값: geojson)

요청 예시:
GET /wia/drought/v1/pdsi/bbox?bbox=-125,25,-66,50&date=2025-12-26

해당 지역의 PDSI 데이터를 담은 GeoJSON FeatureCollection을 반환한다

행정 구역 쿼리

GET /wia/drought/v1/{index}/region

쿼리 매개변수:
  region_id (필수): 국가, 주 또는 카운티 코드
  date (선택): ISO 8601 날짜

요청 예시:
GET /wia/drought/v1/pdsi/region?region_id=US-CA

응답 예시:
{
  "wia_version": "1.0",
  "data_type": "pdsi_regional",
  "region": {
    "id": "US-CA",
    "name": "California",
    "type": "state"
  },
  "timestamp": "2025-12-26T00:00:00Z",
  "summary": {
    "mean_pdsi": -1.8,
    "drought_area_percent": 67.5,
    "severity_distribution": {
      "extreme_drought": 12.3,
      "severe_drought": 28.4,
      "moderate_drought": 26.8,
      "mild_drought": 18.2,
      "near_normal": 14.3
    }
  }
}

경보 구독 서비스

가뭄 상황이 변할 때 자동 알림을 받도록 등록한다.

경보 구독 생성

POST /wia/drought/v1/alerts/subscribe

요청 본문:
{
  "locations": [
    {
      "lat": 40.7128,
      "lon": -74.0060,
      "name": "농장 필지 A"
    },
    {
      "lat": 41.8781,
      "lon": -87.6298,
      "name": "농장 필지 B"
    }
  ],
  "indices": ["pdsi", "spi", "soil_moisture"],
  "thresholds": {
    "pdsi": {
      "warning": -2.0,
      "alert": -3.0,
      "emergency": -4.0
    },
    "soil_moisture": {
      "warning": 25.0,
      "alert": 20.0
    }
  },
  "notification_methods": [
    {
      "type": "webhook",
      "url": "https://app.example.org/drought-alert"
    },
    {
      "type": "email",
      "address": "farmer@example.com"
    }
  ],
  "frequency": "daily"
}

응답:
{
  "subscription_id": "sub_a1b2c3d4e5f6",
  "status": "active",
  "created_at": "2025-12-26T14:30:00Z",
  "locations_count": 2,
  "next_check": "2025-12-27T00:00:00Z"
}

웹훅 경보 형식

구독한 임계값을 초과하면 시스템은 사용자의 웹훅으로 POST 요청을 보낸다.

POST https://app.example.org/drought-alert

요청 본문:
{
  "alert_id": "alert_x1y2z3",
  "subscription_id": "sub_a1b2c3d4e5f6",
  "timestamp": "2025-12-27T08:15:00Z",
  "location": {
    "name": "농장 필지 A",
    "lat": 40.7128,
    "lon": -74.0060
  },
  "trigger": {
    "index": "pdsi",
    "value": -3.2,
    "threshold": "alert",
    "threshold_value": -3.0
  },
  "current_conditions": {
    "pdsi": -3.2,
    "spi_12": -2.1,
    "soil_moisture": 18.5
  },
  "severity": "high",
  "recommended_actions": [
    "관개 시스템을 즉시 가동한다",
    "토양 수분을 매일 모니터링한다",
    "작물 보호 조치를 검토한다"
  ]
}

예측 데이터 접근

기상 예보와 모델을 기반으로 한 가뭄 예측에 접근한다.

GET /wia/drought/v1/forecast

쿼리 매개변수:
  lat (필수): 위도
  lon (필수): 경도
  days (필수): 예측 기간 (7, 14, 30, 90)
  model (선택): 특정 예측 모델

요청 예시:
GET /wia/drought/v1/forecast?lat=40.7128&lon=-74.0060&days=30

응답 예시:
{
  "wia_version": "1.0",
  "data_type": "drought_forecast",
  "location": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128]
  },
  "forecast_period": {
    "start": "2025-12-27T00:00:00Z",
    "end": "2026-01-26T00:00:00Z",
    "days": 30
  },
  "predictions": [
    {
      "date": "2026-01-03T00:00:00Z",
      "pdsi_forecast": {
        "mean": -2.8,
        "confidence_low": -3.4,
        "confidence_high": -2.2,
        "probability_drought": 0.85
      }
    },
    ...
  ],
  "outlook": {
    "trend": "worsening",
    "confidence": 0.72,
    "summary": "향후 30일 동안 가뭄 상황이 심화될 것으로 예상됨"
  }
}

일괄 내보내기 엔드포인트

연구와 대규모 분석을 위한 대량 데이터 내보내기 기능이다.

POST /wia/drought/v1/export

요청 본문:
{
  "region": {
    "type": "bbox",
    "coordinates": [-125, 25, -66, 50]
  },
  "indices": ["pdsi", "spi", "ndvi"],
  "time_range": {
    "start": "2020-01-01",
    "end": "2025-12-26"
  },
  "format": "netcdf",
  "email": "researcher@example.org"
}

응답:
{
  "export_id": "exp_abc123",
  "status": "processing",
  "estimated_completion": "2025-12-26T18:00:00Z",
  "estimated_size_mb": 2450,
  "download_url": null
}

// 내보내기 상태 확인
GET /wia/drought/v1/export/exp_abc123

// 완료 시:
{
  "export_id": "exp_abc123",
  "status": "complete",
  "completed_at": "2025-12-26T17:45:00Z",
  "size_mb": 2385,
  "download_url": "https://exports.example.org/exp_abc123.nc",
  "expires_at": "2025-12-29T17:45:00Z"
}

오류 처리

표준화된 오류 응답은 개발자가 통합 문제를 디버깅하는 데 도움을 준다.

표준 오류 형식

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "위도는 -90에서 90 사이여야 한다",
    "details": {
      "parameter": "lat",
      "provided": "95.5",
      "valid_range": [-90, 90]
    },
    "request_id": "req_xyz789",
    "documentation_url": "https://docs.example.org/errors#INVALID_PARAMETERS"
  }
}

HTTP 상태	오류 코드	의미	해결 방법
400	INVALID_PARAMETERS	쿼리 매개변수가 올바르지 않음	매개변수 형식과 범위를 확인한다
401	UNAUTHORIZED	API 키가 없거나 유효하지 않음	유효한 인증 정보를 제공한다
404	DATA_NOT_FOUND	해당 위치/날짜의 데이터가 없음	다른 위치나 날짜로 시도한다
429	RATE_LIMIT_EXCEEDED	요청이 너무 많음	잠시 기다린 후 다시 시도한다
500	INTERNAL_ERROR	서버 처리 오류	request_id와 함께 지원팀에 문의한다

요청 속도 제한 및 할당량

모든 API 응답에는 요청 속도 제한 헤더가 포함된다.

HTTP/1.1 200 OK
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1766793600
X-RateLimit-Window: daily

장 요약

이 장에서는 WIA 표준의 2단계인 API 인터페이스 사양을 상세히 다루었다. 현재 가뭄 상태, 과거 시계열, 공간 쿼리, 예측 데이터에 접근하기 위한 RESTful 엔드포인트 설계를 살펴보았다. 또한 공개 접근부터 프리미엄 OAuth에 이르는 인증 방식, 웹훅 알림을 활용한 경보 구독 서비스, 연구를 위한 대량 내보내기 기능을 다루었다. 표준화된 오류 처리와 요청 속도 제한은 가뭄 정보에 대한 안정적이고 공정한 접근을 보장한다.

핵심 요점

RESTful 설계: 일관된 URL 구조(/wia/drought/v1/{resource}), 표준 HTTP 메서드, JSON 응답 덕분에 API가 익숙하고 통합하기 쉽다.
유연한 인증: 공개 접근(100 요청/일), API 키(10K 요청/일), OAuth(100K+ 요청/일)를 지원하여 접근성과 보안, 공정 사용 사이의 균형을 맞춘다.
포괄적인 쿼리: 지점 기반, 경계 상자, 행정 구역, 시계열 엔드포인트를 통해 개별 농장 모니터링부터 대륙 규모 분석까지 다양한 애플리케이션이 가능하다.
선제적 경보: 임계값을 설정할 수 있는 웹훅 및 이메일 구독을 통해 자동 대응 시스템과 조기 경보 애플리케이션을 구현할 수 있다.
연구 지원: NetCDF 형식을 지원하는 일괄 내보내기 엔드포인트를 통해 대규모 기후 연구와 과거 가뭄 분석이 가능하다.

복습 질문

WIA API의 계층형 접근 등급(공개, 등록, 프리미엄, 연구)이 개방형 데이터 원칙과 지속 가능한 서비스 운영 사이에서 어떻게 균형을 맞추는지 설명하라. 각 등급은 구체적으로 어떤 사용 사례를 가능하게 하는가?
지점 기반 쿼리(GET /pdsi?lat=...&lon=...)와 공간 쿼리(GET /pdsi/bbox)를 비교하라. 각 방식은 어떤 상황에서 더 적합한가?
경보 구독 시스템이 등록부터 웹훅 알림까지 어떻게 작동하는지 설명하라. 이러한 푸시 기반 방식은 애플리케이션이 데이터를 반복적으로 폴링하는 방식에 비해 어떤 이점이 있는가?
표준화된 오류 응답 형식을 분석하라. request_id와 documentation_url 같은 필드는 통합 문제를 디버깅할 때 개발자 경험을 어떻게 개선하는가?
예측 엔드포인트의 신뢰 구간(confidence_low, confidence_high)에 대해 논하라. 단일 예측값만 제공하는 대신 예측의 불확실성을 전달하는 것이 왜 중요한가?
일괄 내보내기 기능을 평가하라. 이메일 알림을 요구하고 임시 다운로드 URL을 제공하는 방식은 사용자 편의성과 서버 자원 관리를 각각 어떻게 해결하는가?

다음 장 미리 보기

데이터 형식(1단계)과 API 인터페이스(2단계)가 확립되었으므로, 제6장에서는 3단계인 프로토콜 표준을 살펴본다. 원시 위성 영상과 센서 데이터가 표준화된 가뭄 지수로 처리되는 과정을 검토하며, 모든 WIA 준수 시스템에서 일관되고 신뢰할 수 있는 가뭄 정보를 보장하는 대기 보정, 구름 마스킹, NDVI 계산, 증발산 모델링, 품질 관리 절차를 다룬다.

← 제4장 제6장: 3단계 - 프로토콜 →