워드프레스 API 연동 및 키 발급부터 글쓰기 자동화까지 (REST API 사용법 총정리)

워드프레스 REST API란 무엇이고 왜 사용할까요

프론트엔드 개발을 하다 보면 화면을 그리는 것만큼이나 데이터를 주고받는 백엔드와의 통신이 중요해집니다. 특히 블로그나 콘텐츠 관리 시스템을 활용해 서비스를 구축할 때 워드프레스는 강력한 선택지가 되는데 이때 핵심적인 역할을 하는 것이 바로 REST API입니다. 초기에는 단순히 글을 쓰고 관리하는 도구였던 워드프레스가 이제는 독립된 백엔드 서버로 기능할 수 있는 이유가 바로 이 인터페이스 덕분입니다.

API의 기본 개념과 프론트엔드 연동의 이해

API는 애플리케이션 프로그래밍 인터페이스의 약자로 서로 다른 소프트웨어가 소통할 수 있도록 돕는 통로입니다. 웹 개발에서 REST API는 HTTP 프로토콜을 그대로 사용하여 자원을 읽고 쓰고 수정하고 삭제하는 방식을 의미합니다. 예를 들어 리액트나 뷰 같은 자바스크립트 라이브러리로 프론트엔드를 개발할 때 사용자가 화면에서 글 목록을 요청하면 브라우저는 워드프레스 서버로 HTTP GET 요청을 보냅니다. 서버는 데이터베이스에서 글 정보를 찾아 JSON 형식으로 응답하고 프론트엔드는 이 데이터를 받아 화면에 렌더링하게 됩니다.

실무에서 이 구조가 강력한 이유는 뷰단과 데이터 관리단이 완벽하게 분리되기 때문입니다. 디자인 변경이나 사용자 인터페이스 수정이 필요할 때 워드프레스 관리자에 접속해 코드를 고칠 필요 없이 프론트엔드 코드만 수정하면 됩니다. 또한 모바일 애플리케이션이나 다른 외부 서비스에서도 동일한 데이터 소스를 공유할 수 있어 확장성이 뛰어납니다.

워드프레스에서 REST API가 제공하는 핵심 기능

워드프레스는 버전 4.7부터 코어에 REST API가 기본으로 통합되어 별도의 복잡한 설정 없이도 즉시 사용할 수 있습니다. 개발자가 자주 활용하는 핵심 기능은 다음과 같습니다.

포스트 및 페이지 관리: 새로운 블로그 글이나 페이지를 작성하고 수정하고 삭제하는 요청을 코드로 제어할 수 있습니다.
사용자 인증 및 관리: 로그인한 사용자의 권한을 확인하고 회원 정보를 조회하거나 생성할 수 있습니다.
미디어 업로드: 이미지나 동영상 같은 미디어 파일을 서버에 업로드하고 게시물과 연결할 수 있습니다.
댓글 시스템 연동: 방문자들이 남긴 댓글을 조회하거나 새로운 댓글을 등록하는 기능을 비동기로 구현할 수 있습니다.

이러한 기능들을 조합하면 워드프레스를 헤드리스 CMS 형태로 활용하여 완전히 커스텀된 웹사이트를 구축할 수 있습니다. 공식적인 엔드포인트 구조와 사용 가능한 매개변수 대한 자세한 정보는 워드프레스 개발자 문서에서 상세하게 확인할 수 있습니다.

워드프레스 API 키 발급 및 인증 설정 방법

프론트엔드 개발을 하다 보면 외부 시스템에서 워드프레스를 헤드리스 CMS처럼 활용해 데이터를 가져오거나 자동으로 글을 발행해야 하는 요구사항을 자주 마주하게 됩니다. 워드프레스는 기본적으로 강력한 REST API를 제공하므로, 올바른 인증 방식만 설정하면 외부에서 안전하게 사이트를 제어할 수 있습니다.

Application Passwords를 이용한 기본 인증 설정

워드프레스 5.6 버전 이후부터는 별도의 플러그인 설치 없이도 코어 기능으로 Application Passwords(응용 프로그램 비밀번호)를 지원합니다. 이 방식은 관리자 계정의 실제 비밀번호를 노출하지 않고, API 요청 전용의 임시 비밀번호를 발급받아 사용하는 방식입니다.

키를 발급받고 설정하는 절차는 다음과 같습니다.

운영 중인 워드프레스 관리자 페이지(예: 워드프레스 공식 사이트 참고)에 로그인합니다.
좌측 메뉴에서 사용자, 그리고 프로필 순으로 이동합니다.
페이지 하단으로 스크롤하면 응용 프로그램 비밀번호 항목이 나타납니다.
새 응용 프로그램 비밀번호 이름에 연동할 서비스명을 입력하고 새 응용 프로그램 비밀번호 추가 버튼을 누릅니다.
화면에 생성된 16자리의 비밀번호를 복사합니다. 이 값은 다시 조회할 수 없으므로 반드시 안전한 곳에 보관해야 합니다.

발급받은 비밀번호를 사용할 때는 HTTP 요청 헤더에 Authorization 속성을 추가해야 합니다. 이때 관리자 계정의 이메일 또는 아이디와 방금 발급받은 16자리 비밀번호를 콜론으로 연결한 뒤, Base64 방식으로 인코딩하여 전달하는 방식을 사용합니다.

보안을 강화하는 토큰 기반 인증 방식 살펴보기

앞서 살펴본 기본 인증 방식은 구현이 단순하다는 장점이 있지만, 매 요청마다 계정 정보와 결합된 인증 값을 전송해야 하므로 보안상 리스크가 존재합니다. 특히 다중 사용자가 접근하거나 공공 네트워크 환경에서는 토큰 기반 인증 방식을 사용하는 것이 실무에서 훨씬 안전합니다.

토큰 기반 인증은 주로 JWT (JSON Web Token)를 활용합니다. 사용자가 올바른 자격 증명을 보내면 서버는 유효기간이 포함된 토큰을 발행해주고, 클라이언트는 이후 요청에서 이 토큰을 헤더에 담아 전송하는 방식입니다.

워드프레스에서 JWT를 사용하기 위한 핵심 특징은 다음과 같습니다.

워드프레스 기본 기능에는 토큰 발행 기능이 포함되어 있지 않으므로 JWT Authentication for WP REST API와 같은 플러그인을 설치하고 활성화해야 합니다.
서버 환경 설정 파일이나 wp-config.php에 별도의 시크릿 키를 지정하여 토큰 위변조를 방지해야 합니다.
로그인 요청을 통해 발급받은 토큰은 프론트엔드 로컬 스토리지나 세션 스토리지에 안전하게 저장한 뒤, API 호출 시 Bearer Token 형태로 헤더에 포함시킵니다.
토큰이 만료되었을 때를 대비해 리프레시 토큰 로직을 함께 구현하는 것이 실무 개발에서 중요합니다.

프로젝트의 규모와 보안 요구사항에 따라 초기에는 간편한 응용 프로그램 비밀번호로 빠르게 연동을 테스트하고, 서비스가 고도화되거나 사용자 권한이 세분화될 때는 토큰 기반 인증으로 마이그레이션하는 전략을 권장합니다.

JavaScript로 워드프레스 포스팅 자동화 구현하기

워드프레스 REST API를 활용하여 인증 설정을 마쳤다면, 이제 프론트엔드 환경이나 Node.js 서버에서 실제로 글을 등록하는 자동화 코드를 작성할 차례입니다. 자바스크립트의 내장 함수인 Fetch API를 이용하면 별도의 복잡한 라이브러리 설치 없이도 워드프레스에 포스팅을 전송할 수 있습니다.

Fetch API를 활용해 새 글 등록 요청 보내기

워드프레스에 새 글을 작성하는 것은 REST API의 POST 요청에 해당합니다. 엔드포인트 주소는 보통 사이트 주소 뒤에 /wp-json/wp/v2/posts를 붙인 형태가 됩니다. 요청을 보낼 때 가장 중요한 점은 권한 인증을 위한 헤더 설정과 JSON 형식의 본문 데이터 구성입니다.

실제 자바스크립트 코드 작성 예시는 다음과 같습니다.

const createWordPressPost = async () => {
  const siteUrl = 'https://your-wordpress-site.com/wp-json/wp/v2/posts';
  const username = 'your-username';
  const appPassword = 'your-application-password';

  // Basic 인증을 위한 Base64 인코딩
  const credentials = btoa(username + ':' + appPassword);

  const postData = {
    title: '자바스크립트로 자동 발행한 포스팅',
    content: '이 글은 REST API와 Fetch를 통해 자동으로 등록된 컨텐츠입니다.',
    status: 'publish' // 'draft'로 설정하면 임시글로 저장됩니다.
  };

  try {
    const response = await fetch(siteUrl, {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + credentials,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(postData)
    });

    if (!response.ok) {
      throw new Error('서버 응답에 실패했습니다. 상태 코드: ' + response.status);
    }

    const result = await response.json();
    console.log('포스팅 등록 성공:', result);
  } catch (error) {
    console.error('포스팅 등록 중 에러 발생:', error);
  }
};

위 코드에서 btoa 함수는 사용자 이름과 애플리케이션 비밀번호를 HTTP Basic 인증 표준에 맞게 인코딩해 줍니다. status 필드를 ‘publish’로 설정하면 즉시 발행되며, ‘draft’로 설정하면 초안 상태로 저장되므로 테스트 과정에서 유용하게 쓸 수 있습니다. 더 자세한 엔드포인트 명세는 워드프레스 REST API 공식 문서를 참고하면 도움이 됩니다.

실무에서 자주 마주하는 에러 대처 팁

실무에서 워드프레스 API를 연동하다 보면 예상치 못한 에러와 마주하게 됩니다. 특히 CORS 이슈나 권한 부족 문제가 빈번하게 발생하므로 미리 대처법을 알아두는 것이 좋습니다.

CORS (교차 출처 리소스 공유) 에러: 브라우저 환경에서 직접 외부 워드프레스 사이트로 요청을 보낼 때 주로 발생합니다. 워드프레스가 설치된 서버의 설정이나 플러그인을 통해 허용된 도메인(Access-Control-Allow-Origin)을 지정해주어야 합니다. 만약 해결이 어렵다면 프론트엔드에서 직접 요청하기보다 백엔드 서버나 Node.js 환경에서 API를 호출하는 우회 방식을 추천합니다.
401 Unauthorized (인증 실패): 아이디와 비밀번호가 틀렸거나, 일반 로그인 비밀번호를 그대로 사용했을 때 발생합니다. 반드시 사용자 프로필 하단에서 새로 생성한 애플리케이션 비밀번호를 공백 없이 정확히 입력했는지 확인해야 합니다.
403 Forbidden (권한 없음): 인증은 성공했으나 해당 작업을 수행할 권한이 없는 경우입니다. 사용하는 계정이 관리자(Administrator) 또는 편집자(Editor) 권한을 가지고 있는지, 그리고 API 요청 시 올바른 사용자의 인증 정보를 사용하고 있는지 점검해야 합니다.
400 Bad Request (잘못된 요청): 필수 필드인 title이나 content의 데이터 타입이 잘못되었거나 누락되었을 때 발생합니다. 요청 객체(body)의 JSON 구조가 올바른지 console.log로 미리 찍어 확인하는 습관이 실수를 줄이는 가장 빠른 길입니다.

초기 연동 단계에서는 개발자 도구의 네트워크 탭과 워드프레스 서버의 에러 로그를 함께 확인해가며 원인을 파악하는 것이 시행착오를 줄이는 핵심 노하우입니다.