WordPress REST API로 초안을 올릴 때 주의할 점

WordPress REST API로 초안을 올릴 때 먼저 나눌 것

WordPress REST API로 글을 올릴 때 제일 먼저 정할 건 “자동 발행”이 아니라 “초안 업로드까지만 자동화할지”다. 내 경우에는 여기서 한 번 꼬였다. API로 글이 올라가니까 발행까지 같이 밀어도 될 것 같았는데, 실제로는 HTML 변환, 썸네일, 카테고리, 문단 모양을 한 번 보고 나서 발행하는 쪽이 훨씬 덜 불안했다.

초안 업로드 자체는 단순하다. /wp-json/wp/v2/posts 쪽으로 글을 만들고, 상태를 draft로 둔다. 문제는 그 앞뒤다. 인증이 애매하면 글 생성이 실패하고, 본문 변환이 애매하면 올라간 글이 이상하게 보인다. 발행까지 자동으로 묶어두면 그 이상한 상태가 바로 공개된다.

`draft` 상태는 그냥 안전장치가 아니다

status를 draft로 보내는 건 실수 방지용 버튼에 가깝다. API 호출이 성공했다는 말과, 사람이 읽기 좋은 글이 됐다는 말은 다르다.

WordPress REST API의 posts 엔드포인트는 글을 만들 때 status 값을 받을 수 있고, 공식 문서 기준으로 publish, future, draft, pending, private 같은 상태를 쓴다. 나는 여기서 기본값에 기대지 않고 draft를 명시하는 쪽이 낫다고 본다.

값	내 작업에서의 의미
draft	자동화가 올린 임시 글. 관리자 화면에서 확인하고 손으로 발행한다
pending	편집 승인 흐름이 따로 있을 때 쓸 만하다
publish	API 호출 성공과 동시에 공개된다. 초안 파이프라인에는 너무 세다

처음엔 “어차피 내가 만든 글인데 바로 발행해도 되지 않나” 싶었다. 그런데 제목에 따옴표가 깨져 있거나, 코드 블록이 이상하게 붙거나, 첫 문단이 너무 길게 들어간 걸 보고 나면 생각이 바뀐다. 초안으로 올려두면 실패가 공개 사고가 아니라 수정 거리로 남는다.

인증은 글 쓰기 권한 문제로 보면 된다

WordPress REST API는 공개 글을 읽는 것과 글을 만드는 것이 다르다. 공개 글 목록은 인증 없이도 볼 수 있지만, 새 글을 만들거나 기존 글을 고치려면 해당 사용자에게 권한이 있어야 한다.

외부 스크립트에서 올리는 경우에는 보통 Application Passwords를 쓴다. WordPress 5.6부터 들어간 기능이고, 사용자 비밀번호를 그대로 스크립트에 넣는 방식보다 낫다. 애플리케이션별로 만들고, 필요 없어지면 그 비밀번호만 폐기할 수 있다.

여기서 헷갈리기 쉬운 점이 하나 있다. Application Password는 wp-admin 로그인용 비밀번호가 아니다. 브라우저 로그인에 쓰는 게 아니라, REST API 같은 외부 요청에서 인증할 때 쓰는 별도 비밀번호다. 한 번 만들 때만 값이 보이니, 저장 위치도 처음부터 정해두는 편이 좋다.

내가 체크하는 기준은 대충 이렇다.

확인할 것	왜 보는지
API 호출이 HTTPS로 나가는지	Application Password는 HTTPS 요청에 쓰는 쪽으로 봐야 한다
글 작성 권한이 있는 사용자에게 발급했는지	인증은 됐는데 작성 권한이 없으면 막힌다
개인 계정 비밀번호와 분리했는지	자동화가 털려도 주 비밀번호까지 바꾸는 상황을 줄인다
실패 로그에 비밀번호가 찍히지 않는지	디버깅하다가 제일 쉽게 새는 곳이 로그다

Markdown을 그대로 보내면 WordPress가 알아서 예쁘게 해주지 않는다

내가 처음에 제일 대충 봤던 부분이 본문 변환이었다. 메모는 Markdown으로 쓰고, WordPress에는 content로 보내면 되겠지 싶었다. 그런데 REST API가 Markdown을 자동으로 HTML로 바꿔주는 건 아니다. 그런 처리는 별도 플러그인이나 내 파이프라인 쪽 책임으로 봐야 한다.

그래서 초안 업로드 전에는 본문을 HTML로 바꿔서 보낸다. 특히 코드 블록, 목록, 링크, 인용문은 눈으로 봐야 한다. 변환기는 성공했다고 하는데 WordPress 편집기에서 보면 줄바꿈이 이상하거나, <pre> 안쪽이 한 줄로 뭉개져 있는 일이 있다.

내 경우에는 아래 순서가 덜 꼬였다.

단계	보는 것
원문 작성	Markdown 기준으로 사람이 읽기 좋은지 본다
HTML 변환	코드 블록, 목록, 링크가 깨지지 않는지 본다
REST API 업로드	title, content, status=draft 정도만 먼저 안정화한다
관리자 화면 확인	블록 편집기에서 본문이 어떻게 잡히는지 본다
수동 발행	썸네일, 카테고리, 태그, 미리보기를 보고 눌러도 늦지 않다

Gutenberg 블록까지 정교하게 맞추려면 또 다른 문제가 된다. 그냥 HTML 본문으로 충분한지, 블록 주석까지 만들어야 하는지부터 갈린다. 처음부터 블록 구조를 완벽히 만들려고 하면 파이프라인이 빨리 무거워진다. 나는 일단 HTML 초안으로 올리고, WordPress 안에서 최종 모양을 보는 쪽이 편했다.

자동 발행을 분리하면 디버깅이 쉬워진다

초안 업로드와 발행을 분리하면 문제가 생겼을 때 원인을 나누기 쉽다. API 인증 문제인지, 변환 문제인지, WordPress 편집 단계 문제인지가 갈린다.

한 번에 publish까지 해버리면 로그를 보면서도 마음이 급해진다. 글이 이미 공개됐으니까. 반대로 draft까지만 자동화하면 실패 범위가 작다. 올라간 글을 지우거나 고치면 되고, 공개 페이지에는 영향이 없다.

내가 나눈 책임은 이 정도다.

자동화가 해도 되는 것	사람이 보는 것
제목 넣기	제목이 블로그 톤에 맞는지
HTML 본문 넣기	문단 간격과 코드 블록이 괜찮은지
draft 상태로 저장	발행해도 되는 글인지
기본 카테고리 지정	최종 카테고리, 태그, 썸네일
업로드 결과 ID 저장	미리보기에서 실제로 읽히는지

여기서 핵심은 API가 못 믿을 물건이라는 뜻이 아니다. API는 자기 일을 한다. 다만 “글을 저장했다”와 “발행할 만하다” 사이에는 편집자의 눈으로 봐야 하는 구간이 남는다.