워드프레스는 설치한 순간부터 REST API 를 켜 두고 있습니다. 플러그인도 설정도 필요 없습니다. 브라우저에서 /wp-json/ 를 열면 이 사이트가 공개하는 네임스페이스와 라우트가 전부 JSON 으로 나옵니다. 헤드리스를 할 계획이 없어도 알아 둘 값어치가 있습니다 — 블록 에디터가 글을 저장하는 경로가 바로 이것이기 때문입니다.
이미 열려 있는 것
코어가 등록하는 주 네임스페이스는 wp/v2 입니다. 글 · 페이지 · 미디어 · 카테고리 · 태그 · 사용자 · 설정 · 검색이 여기 들어 있고, 커스텀 포스트 타입은 등록할 때 노출을 선언한 것만 합류합니다 — 그 선언이 다음 회차의 주제입니다.
GET /wp-json/ 네임스페이스와 라우트 목록
GET /wp-json/wp/v2/posts 발행된 글 (인증 불요)
GET /wp-json/wp/v2/posts/12 글 하나
OPTIONS /wp-json/wp/v2/posts 이 라우트의 스키마와 허용 메서드마지막 줄이 특히 쓸모 있습니다. OPTIONS 로 라우트를 두드리면 인자 목록 · 타입 · 필수 여부 · 기본값이 스키마로 돌아옵니다. 문서를 찾기 전에 여기부터 보는 편이 빠르고, 무엇보다 이 설치에 실제로 등록된 내용이라 문서보다 정확합니다. 플러그인이 라우트를 더했는지도 여기서 드러납니다.
읽기와 쓰기의 경계는 뚜렷합니다. 발행된 콘텐츠의 읽기는 인증이 필요 없고, 나머지는 거의 전부 인증을 요구합니다.
응답의 형태 — context · _fields · _embed
같은 리소스라도 context 에 따라 돌려주는 필드가 달라집니다. 기본값 view 는 공개 필드만, embed 는 요약 몇 개만, edit 는 원본(raw) 값까지 주는데 edit 는 권한이 있어야 합니다.
목록에서 필요한 것이 제목과 주소뿐이라면 _fields=id,title,link 로 잘라 받습니다. 응답이 작아지고 서버가 만들지 않아도 될 필드가 줄어듭니다. 반대로 _embed 를 붙이면 대표 이미지 · 작성자 · 텀이 _embedded 안에 함께 실려 와 요청 횟수가 줄어듭니다. 둘은 방향이 반대인 최적화라, 요청 하나에서 무엇을 아낄지 먼저 정하고 골라야 합니다.
페이지네이션과 오류
목록은 기본 10건이고 per_page 로 조정하되 상한이 100 입니다. 전체 개수는 본문이 아니라 응답 헤더에 옵니다.
X-WP-Total: 137
X-WP-TotalPages: 14이 헤더를 읽지 않고 “빈 페이지가 나올 때까지” 도는 클라이언트를 자주 봅니다. 마지막 페이지 다음을 요청하면 빈 배열이 아니라 400 오류가 돌아오므로, 그 방식은 매 순회마다 오류를 한 번 만들고 끝납니다.
오류는 HTTP 상태 코드와 JSON 본문 양쪽으로 옵니다. 본문의 모양은 언제나 같습니다.
{"code":"rest_post_invalid_id","message":"올바르지 않은 글 ID 입니다.","data":{"status":404}}code 는 기계가 분기할 문자열이고 message 는 사람이 읽을 문장입니다. 클라이언트에서 message 로 분기하지 마세요 — 사이트 로케일이 바뀌면 그 문장이 바뀝니다. 같은 이유로 우리가 만드는 라우트도 code 를 안정된 식별자로 정해 두어야 합니다.
API 를 전제로 한 개발 습관 전반은 개발 워크플로우 아카이브에 모여 있고, 남이 만든 환경 위에서 이런 계층을 건드릴 때의 실제 절차는 작업 과정에 공개돼 있습니다.
다음 회차
코어 라우트는 여기까지입니다. 다음 회차는 우리가 만든 포스트 타입과 메타를 이 목록에 합류시키는 방법 — show_in_rest 가 정확히 무엇을 하고, 메타에서는 왜 그 한 줄로 부족한지를 다룹니다.