API 문서를 읽는 것과 API를 이해하는 것은 다르다
Notion API로 페이지 이동을 시도하며 배운 것
문제
옵시디언에서 프로젝트 문서를 관리하다 보니, 외부 서비스와 연동할 일이 생긴다. 이번에는 Notion이었다. 클라이언트와 공유하는 문서가 Notion에 있었고, 구조를 정리할 필요가 있었다.
흩어져 있는 문서들을 새 상위 페이지 아래로 모으는 단순한 작업. 옵시디언에서 파일을 폴더로 옮기듯이, Notion에서도 페이지를 페이지 아래로 옮기면 될 줄 알았다.
AI에게 시켰다. “블루망고 페이지 만들고, 기존 두 페이지를 그 아래로 옮겨줘.”
Notion API로 페이지를 생성하는 건 잘 됐다. 블록을 추가하는 것도 됐다. 그런데 기존 페이지를 새 페이지 아래로 이동하는 건 안 됐다.
에러가 나는 것도 아니었다. 요청은 성공했다. 응답도 200이 왔다. 그런데 페이지가 안 움직였다.
기존 접근의 한계
처음엔 권한 문제라고 생각했다. Integration에 페이지 접근 권한을 다시 줬다. 그래도 안 됐다.
코드를 다시 봤다. PATCH 요청으로 parent를 변경하는 방식이었다.
// 이론적으로는 이렇게 되어야 했다
PATCH /v1/pages/{page_id}
{
"parent": { "page_id": "new_parent_id" }
}
// 응답: 200 OK ✅
// 결과: 페이지 안 움직임 ❌문법적으로 틀린 건 없었다. API 문서에도 parent가 페이지 속성으로 나와 있었다.
문제는 내가 읽지 않은 한 줄에 있었다.
“The parent property cannot be updated via the API.”
parent는 read-only였다. 페이지를 생성할 때만 지정할 수 있고, 이후에는 변경할 수 없다.
내가 내린 판단
여기서 두 가지를 생각했다.
첫째, API의 ‘한계’를 먼저 파악했어야 했다.
보통 API 연동할 때 이렇게 접근한다:
일반적인 접근 (할 수 있는 것 중심)
──────────────────────────────────
1. 어떤 기능이 있나? ← 여기에 집중
2. 어떻게 호출하나?
3. 응답 형식은?
더 나은 접근 (할 수 없는 것 중심)
──────────────────────────────────
1. 어떤 기능이 없나? ← 여기를 먼저
2. 어떤 속성이 read-only인가?
3. 어떤 작업에 제약이 있나?
4. Rate limit은?
5. 그 다음에 가능한 것 확인이 질문을 먼저 했으면 30분은 아꼈을 것이다.
둘째, API 설계에는 이유가 있다.
Notion이 parent 변경을 막은 이유를 생각해봤다. 아마도:
- 페이지 트리 구조의 일관성 보장
- 이동 시 발생할 수 있는 권한 충돌 방지
- 버전 관리 및 히스토리 복잡성
단순히 “기능이 없네”가 아니라 **“왜 없을까”**를 생각하면, 다른 API에서도 비슷한 패턴을 예측할 수 있게 된다.
결과와 배운 점
결국 페이지 이동은 Notion UI에서 수동으로 했다. 드래그 앤 드롭 3초.
우회 방법도 있었다:
- 새 페이지를 원하는 위치에 생성
- 기존 페이지 내용을 블록 단위로 복사
- 기존 페이지 삭제 또는 아카이브
하지만 복잡한 우회보다 단순한 수동 작업이 나았다. 이것도 판단이다.
그리고 이 경험을 옵시디언에 기록해뒀다. 3-Resources/ 아래 API 삽질 노트로. 핵심만 적었다:
## Notion API 제약사항
- `parent`는 read-only → 페이지 이동 불가
- 우회: 새 페이지 생성 → 블록 복사 → 원본 삭제
- 판단: 1회성이면 UI에서 수동으로 하는 게 빠름이런 메모가 쌓이면 나중에 같은 API를 다시 쓸 때 시간을 아낀다. “Notion API”로 검색하면 바로 나오니까. 삽질 로그는 가장 실용적인 레퍼런스다.
네 가지를 배웠다.
1. “가능한 것” 목록보다 “불가능한 것” 목록을 먼저 확인하라.
대부분의 삽질은 “이게 될 줄 알았는데 안 되네”에서 시작한다. API 연동 전에 Limitations, Constraints, Read-only properties 섹션을 먼저 읽으면 시간이 절약된다.
2. 에러 없이 실패하는 경우가 있다.
200 OK가 성공을 보장하지 않는다. 요청은 받았지만 처리하지 않을 수 있다. 응답 본문을 확인하고, 실제로 변경됐는지 검증해야 한다.
3. 모든 걸 자동화할 필요는 없다.
이번 경우, API 우회 로직을 만드는 시간보다 수동으로 드래그하는 게 빨랐다. 자동화는 반복에 가치가 있다. 한 번 할 일이면 그냥 하는 게 낫다.
4. 삽질은 기록해야 자산이 된다.
머릿속에만 있으면 다음에 또 삽질한다. 옵시디언이든 어디든, “이 API에서 이건 안 됨”이라고 한 줄 적어두면 미래의 나에게 30분을 선물하는 거다. 특히 AI 에이전트에게 작업을 시킬 때, 이 제약사항 목록을 컨텍스트로 주면 같은 실수를 반복하지 않는다.
생각해볼 질문
당신이 마지막으로 “이게 될 줄 알았는데” 삽질한 건 언제인가?
그 삽질은 문서의 어떤 부분을 안 읽어서 발생했나?