제5장: 2단계 - API 인터페이스

5.1 API 설계 원칙

WIA-ROB-011 API는 RESTful 아키텍처를 기반으로 설계되었으며, 직관적이고 일관된 인터페이스를 제공합니다. 개발자는 최소한의 학습으로 청소 로봇의 모든 기능에 접근할 수 있습니다.

5.2 API 기본 구조

5.2.1 Base URL

https://api.example.com/wia-rob-011/v1

5.2.2 인증

모든 API 요청은 OAuth 2.0 또는 JWT 토큰을 사용한 인증이 필요합니다.

// OAuth 2.0 인증
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

// API 키 (개발/테스트 용도)
X-API-Key: wia_rob_011_api_key_example

5.3 주요 엔드포인트

5.3.1 기기 관리 (Device Management)

메서드	엔드포인트	설명
GET	/robots	등록된 로봇 목록 조회
GET	/robots/{robot_id}	특정 로봇 정보 조회
POST	/robots	새 로봇 등록
PUT	/robots/{robot_id}	로봇 정보 업데이트
DELETE	/robots/{robot_id}	로봇 등록 해제

// 로봇 목록 조회
GET /robots
Response 200 OK:
{
  "total": 2,
  "robots": [
    {
      "id": "CR-2025-001",
      "name": "Living Room Cleaner",
      "type": "vacuum_cleaner",
      "status": "idle",
      "battery": 95,
      "last_seen": "2025-12-29T10:30:00Z"
    },
    {
      "id": "CR-2025-002",
      "name": "Bedroom Cleaner",
      "type": "hybrid_cleaner",
      "status": "charging",
      "battery": 78,
      "last_seen": "2025-12-29T10:28:00Z"
    }
  ]
}

5.3.2 상태 조회 (Status Retrieval)

GET /robots/{robot_id}/status
Response 200 OK:
{
  "robot_id": "CR-2025-001",
  "timestamp": "2025-12-29T10:30:15Z",
  "state": "cleaning",
  "battery": 85,
  "location": {
    "x": 1250,
    "y": 3400,
    "room": "living_room"
  },
  "cleaning": {
    "mode": "auto",
    "progress": 65,
    "area_cleaned": 42.5
  }
}

5.3.3 제어 명령 (Control Commands)

명령	엔드포인트	파라미터
청소 시작	POST /robots/{id}/commands/start	mode, rooms, power_level
청소 중지	POST /robots/{id}/commands/stop	-
일시 정지	POST /robots/{id}/commands/pause	-
재개	POST /robots/{id}/commands/resume	-
복귀	POST /robots/{id}/commands/return	-
구역 청소	POST /robots/{id}/commands/zone	coordinates

// 청소 시작 명령
POST /robots/CR-2025-001/commands/start
Content-Type: application/json

{
  "mode": "auto",
  "rooms": ["living_room", "kitchen"],
  "power_level": "high",
  "iterations": 2
}

Response 202 Accepted:
{
  "task_id": "task_20251229_001",
  "status": "accepted",
  "estimated_duration": 3600,
  "message": "Cleaning task scheduled successfully"
}

5.3.4 스케줄 관리 (Schedule Management)

// 스케줄 생성
POST /robots/{robot_id}/schedules
{
  "name": "Daily Morning Clean",
  "enabled": true,
  "recurrence": {
    "type": "daily",
    "time": "09:00",
    "days": ["mon", "tue", "wed", "thu", "fri"]
  },
  "task": {
    "mode": "auto",
    "rooms": ["living_room", "kitchen"],
    "power_level": "standard"
  }
}

Response 201 Created:
{
  "schedule_id": "sched_001",
  "next_run": "2025-12-30T09:00:00Z"
}

5.3.5 지도 관리 (Map Management)

메서드	엔드포인트	설명
GET	/robots/{id}/maps	저장된 지도 목록
GET	/robots/{id}/maps/{map_id}	특정 지도 다운로드
POST	/robots/{id}/maps	새 지도 업로드
PUT	/robots/{id}/maps/{map_id}/rooms	방 구역 편집
POST	/robots/{id}/maps/{map_id}/zones	금지 구역 추가

// 방 구역 편집
PUT /robots/CR-2025-001/maps/map_001/rooms/room_001
{
  "name": "Living Room",
  "type": "living_room",
  "polygon": [
    {"x": 0, "y": 0},
    {"x": 5000, "y": 0},
    {"x": 5000, "y": 5700},
    {"x": 0, "y": 5700}
  ],
  "cleaning_settings": {
    "power_level": "high",
    "iterations": 2,
    "mop_enabled": false
  }
}

5.3.6 청소 이력 (Cleaning History)

// 청소 이력 조회
GET /robots/{robot_id}/history?limit=10&offset=0&date_from=2025-12-01

Response 200 OK:
{
  "total": 45,
  "limit": 10,
  "offset": 0,
  "history": [
    {
      "session_id": "clean_20251229_001",
      "start_time": "2025-12-29T09:00:00Z",
      "duration": 3600,
      "area_cleaned": 85.3,
      "rooms": ["living_room", "kitchen"],
      "completed": true
    }
  ]
}

5.4 GraphQL API

복잡한 쿼리와 실시간 업데이트가 필요한 경우 GraphQL API를 사용할 수 있습니다.

5.4.1 쿼리 예시

// 여러 로봇의 상태를 한 번에 조회
query GetRobotsStatus {
  robots {
    id
    name
    status {
      state
      battery {
        level
        charging
      }
      location {
        room
      }
      cleaning {
        progress
        areaClean ed
      }
    }
  }
}

// 응답
{
  "data": {
    "robots": [
      {
        "id": "CR-2025-001",
        "name": "Living Room Cleaner",
        "status": {
          "state": "cleaning",
          "battery": { "level": 85, "charging": false },
          "location": { "room": "living_room" },
          "cleaning": { "progress": 65, "areaCleaned": 42.5 }
        }
      }
    ]
  }
}

5.4.2 뮤테이션 예시

// 청소 시작
mutation StartCleaning($robotId: ID!, $params: CleaningParams!) {
  startCleaning(robotId: $robotId, parameters: $params) {
    success
    taskId
    estimatedDuration
    message
  }
}

// 변수
{
  "robotId": "CR-2025-001",
  "params": {
    "mode": "AUTO",
    "rooms": ["living_room", "kitchen"],
    "powerLevel": "HIGH"
  }
}

5.4.3 구독 (Subscriptions)

// 실시간 상태 업데이트 구독
subscription OnStatusUpdate($robotId: ID!) {
  statusUpdated(robotId: $robotId) {
    state
    battery {
      level
    }
    location {
      x
      y
      room
    }
    cleaning {
      progress
    }
  }
}

5.5 오류 처리

API는 표준 HTTP 상태 코드와 상세한 오류 정보를 제공합니다.

상태 코드	의미	사용 사례
200	OK	요청 성공
201	Created	리소스 생성 성공
202	Accepted	명령 접수 (비동기)
400	Bad Request	잘못된 요청 파라미터
401	Unauthorized	인증 실패
403	Forbidden	권한 없음
404	Not Found	리소스 없음
429	Too Many Requests	요청 한도 초과
500	Internal Server Error	서버 오류

// 오류 응답 형식
Response 400 Bad Request:
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid power_level value",
    "details": {
      "field": "power_level",
      "value": "ultra",
      "allowed": ["quiet", "standard", "high", "max"]
    },
    "timestamp": "2025-12-29T10:30:00Z",
    "request_id": "req_abc123"
  }
}

5.6 속도 제한 (Rate Limiting)

API 남용 방지와 공정한 리소스 사용을 위해 속도 제한을 적용합니다.

엔드포인트 유형	제한	기간
상태 조회	60회	분당
제어 명령	30회	분당
지도 다운로드	10회	시간당
이력 조회	100회	시간당

// 속도 제한 헤더
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1703848800

// 제한 초과 시
HTTP/1.1 429 Too Many Requests
Retry-After: 30
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 30 seconds."
  }
}

5.7 페이지네이션

대량의 데이터를 효율적으로 처리하기 위해 페이지네이션을 지원합니다.

// 페이지네이션 파라미터
GET /robots/{robot_id}/history?limit=20&offset=40&sort=start_time:desc

Response:
{
  "total": 150,
  "limit": 20,
  "offset": 40,
  "has_more": true,
  "next": "/robots/CR-2025-001/history?limit=20&offset=60",
  "prev": "/robots/CR-2025-001/history?limit=20&offset=20",
  "data": [...]
}

5.8 웹훅 (Webhooks)

특정 이벤트 발생 시 자동으로 알림을 받을 수 있습니다.

5.8.1 웹훅 등록

POST /webhooks
{
  "url": "https://my-app.example.com/webhook",
  "events": [
    "cleaning.started",
    "cleaning.completed",
    "battery.low",
    "error.occurred"
  ],
  "secret": "webhook_secret_key"
}

Response 201 Created:
{
  "webhook_id": "wh_abc123",
  "url": "https://my-app.example.com/webhook",
  "events": ["cleaning.started", "cleaning.completed", ...],
  "created_at": "2025-12-29T10:30:00Z"
}

5.8.2 웹훅 페이로드

// 청소 완료 이벤트
POST https://my-app.example.com/webhook
X-WIA-Event: cleaning.completed
X-WIA-Signature: sha256=abc123...

{
  "event": "cleaning.completed",
  "timestamp": "2025-12-29T10:30:00Z",
  "robot_id": "CR-2025-001",
  "data": {
    "session_id": "clean_20251229_001",
    "duration": 3600,
    "area_cleaned": 85.3,
    "rooms": ["living_room", "kitchen"]
  }
}

5.9 SDK 및 클라이언트 라이브러리

주요 프로그래밍 언어를 위한 공식 SDK를 제공합니다.

// JavaScript/TypeScript
import { CleaningRobotClient } from '@wia/rob-011-sdk';

const client = new CleaningRobotClient({
  apiKey: 'your_api_key',
  baseURL: 'https://api.example.com'
});

const robots = await client.robots.list();
await client.robots.startCleaning('CR-2025-001', {
  mode: 'auto',
  rooms: ['living_room'],
  powerLevel: 'high'
});

// Python
from wia_rob_011 import CleaningRobotClient

client = CleaningRobotClient(api_key='your_api_key')
robots = client.robots.list()
client.robots.start_cleaning('CR-2025-001',
  mode='auto', rooms=['living_room'])

// Go
import "github.com/wia/rob-011-go"

client := rob011.NewClient("your_api_key")
robots, err := client.Robots.List()
err = client.Robots.StartCleaning("CR-2025-001", ...)