research

Google Tasks API — Task & TaskList 구조

Google Tasks API — Task & TaskList 구조

API: Google Tasks API v1. Calendar API와 별개 API. 출처: Google Tasks API v1 reference 조사 기반.

API 구조 개요

Google Tasks API v1
├── tasklists /
│   ├── list()
│   ├── get(tasklistId)
│   ├── insert()
│   └── delete()
└── tasks /
    ├── list(tasklistId)
    ├── get(tasklistId, taskId)
    ├── insert(tasklistId)
    ├── update(tasklistId, taskId)
    ├── delete(tasklistId, taskId)
    ├── move(tasklistId, taskId)   ← 순서/계층 이동
    └── clear(tasklistId)         ← completed 전부 삭제

TaskList Resource

{
  "kind": "tasks#taskList",
  "id": "string",
  "title": "string",
  "updated": "RFC3339",
  "selfLink": "string",
  "etag": "string"
}

Task Resource (핵심)

{
  "kind": "tasks#task",
  "id": "string",
  "title": "string",
  "notes": "string",

  "status": "needsAction|completed",
  "completed": "RFC3339",
  "deleted": false,
  "hidden": false,

  "due": "RFC3339",           // 마감일 (deadline). 날짜 정보만, 시간 무시
  "scheduled": "RFC3339",     // 캘린더 그리드 표시 날짜. 날짜 정보만

  "parent": "string",         // 부모 task ID. top-level이면 없음. read-only
  "position": "string",       // 정렬 키 (lexicographic). read-only

  "selfLink": "string",
  "updated": "RFC3339",
  "etag": "string",

  "links": [{ "type": "string", "description": "string", "link": "string" }],

  "assignmentInfo": {
    "surfaceType": "DOCUMENT|SPACE",
    "driveResourceInfo": { ... },
    "spaceInfo": { "space": "spaces/{id}" }
  }
}

ERD (Naran 로컬 DB 기준)

핵심 개념

due vs scheduled — 완전히 다른 필드

| 필드 | 의미 | 캘린더 그리드 표시 | |------|------|--------------------| | due | 마감일 (deadline) — "언제까지 해야 하는가" | ❌ | | scheduled | 예정일 — "언제 할 건지, 캘린더에 표시" | ✅ |

둘 다 날짜 정보만 저장 (시간 없음). API에서 시간을 읽거나 쓸 수 없음.

계층 구조 (서브태스크)

  • parent 필드로 부모-자식 관계 표현
  • position은 lexicographic 문자열 → 순서 정렬
  • 제약: assigned task는 계층 구조 불가, 반복 태스크도 계층 불가

반복 태스크

  • API에서 지원 안 함 — UI에서만 생성/편집 가능
  • API로 읽으면 단순 task처럼 보임 (반복 정보 미노출)

Sync 패턴

tasklists.list() → nextSyncToken 저장
tasks.list(tasklistId, syncToken=saved) → 변경분만 수신
410 GONE → 만료, full resync 필요

Tasks API vs Calendar API

| 항목 | Calendar API (Events) | Tasks API | |------|----------------------|-----------| | 개념 | 일정 (시간 블록) | 할 일 (체크리스트) | | 시간 | 시작/종료 시각 있음 | 날짜만 (시간 없음) | | 반복 | RRULE 완전 지원 | UI만, API 미지원 | | 계층 | 없음 | parent로 서브태스크 | | 완료 | status: cancelled | status: completed | | sync | syncToken | syncToken (동일 패턴) |

Naran 설계 시사점

  • due_date (마감일) 와 scheduled_date (예정일) 를 별개 컬럼으로 분리
  • tasklists 테이블 분리 (GCal과 동일하게 컨테이너 개념 명시)
  • parent_task_id 자기참조로 서브태스크 지원
  • 반복 태스크는 자체 recurrence_rule 컬럼으로 관리 → GCal sync 시 단순 task 취급
← research 목록으로홈으로