워드프레스 REST API 간략 이해

워드프레스는 적어도 이 글을 작성한 때 기준에서 PHP 언어 의존도가 높은 시스템으로 자바스크립트^JavaScript 사용 비율이 상대적으로 낮습니다. 이것은 콘텐츠 소비 환경 변화에 대응하기 위한 웹 및 응용프로그램 개발에 한계를 가집니다. 한계는, 나쁘다는 뜻보다 워드프레스가 아닌 외부 응용프로그램 또는 내부에서 워드프레스 콘텐츠에 접근하여 데이터를 가공, 활용하는 방식에 약간의 제한이 있다는 정도로 생각할 수 있습니다. 그러나, 이런 제한적 요소는 코어에서 제공하는 워드프레스 REST API(WP REST API)를 사용하면 문제 될 것이 없습니다.

지난 과정에서 말한 것처럼, 이어지는 워드프레스 REST API 내용은 선택적인 것으로 원하지 않는다면 예제에 적용하지 않아도 됩니다. 또, 워드프레스 REST API는 사용에 초점을 두어야 가치가 있으므로 괜한 개념 이해에 시간을 투자하지 않기를 바랍니다. 워드프레스 REST API 사용에 오히려 요구되는 것은 워드프레스 쿼리, 커스텀 포스트 타입과 분류, 커스텀 필드, 훅, 조건 태그 등의 기본 핵심 구성 요소의 사용 및 콘텐츠 생산 경험입니다. 추가로 자바스크립트 및 특정 프레임 워크 등에 관한 최소한의 지식이 필요합니다. 예제에서는 이미지 포스트 아카이브 페이지에서 ‘더보기’ 및 간단한 ‘커스텀 엔드포인트’ 정도를 구성하는데, 최소한의 기초적인 방식을 사용하므로 관련 지식이 없어도 염려할 필요는 없습니다.

키워드

REST API 정의에 관한 일반 정보를 보면 ‘REST’, ‘RESTful’, ‘AJAX, ‘JSON, ‘JavaScript’, ‘HTTP’, ‘Method’, ‘URI’, ‘CRUD’, ‘Endpoint’ 등의 키워드나 키워드를 포함한 코드를 늘 볼 수 있습니다. 어떤 키워드는 개념의 요소이며, 어떤 키워드는 프로그래밍 언어입니다. 이러한 키워드에 관한 정의는 웹에 차고 넘치므로 서술할 필요가 없고, 개념 요소에 많은 시간을 할당하지 않는 것이 좋습니다. REST API 사용에 의한 실제 또는 가상 기준의 예제를 구성하면서 과정과 결과를 한 번이라도 더 경험하는 것이 현명하며 효율적입니다. 그것으로 개념의 이해를 더하면 됩니다. 그래도 혹시 처음이라면 검색하여 한 번 정도 읽어보세요.

REST API Handbook

REST API 일반론을 웹에서 찾는다면, 기본의 워드프레스 REST API 정보는 코덱스에서 얻어야 합니다. 워드프레스 REST API는 ‘엔드포인트 콜렉션’으로 부를 만큼 특정 데이터(포스트 타입, 분류, 사용자, 메타 데이터, 설정 등) 집합을 얻을 수 있는 경로를 완성하여 제공하는데, 늘 개선되므로 새로운 응용프로그램을 구성해야 한다면 코덱스 해당 문서를 먼저 확인하는 것이 좋습니다. 다음 링크의 문서 정도를 우선 참고하고, 링크의 하위 문서와 나머지는 필요할 때마다 찾으면 됩니다. 코덱스의 REST API 문서는 내용이 많은 것처럼 보이지만, 둘러보면 모두 단편의 짧은 내용이므로 워드프레스의 다른 문서보다 쉽습니다.

• REST API Handbook
• Reference
• Frequently Asked Questions
• Changelog

반복하는 것으로, 워드프레스 REST API는 워드프레스 쿼리, 필드, 포스트 타입 등의 기본 핵심 구성 요소에 관한 경험이 선행될 때 더 편리하고 쉽게 사용할 수 있습니다.

워드프레스 REST API 기본

워드프레스 4.7 버전부터 코어에 추가되어 플러그인 설치 없이 사용할 수 있는 워드프레스 REST API는 PHP 중심의 워드프레스와 다른 프로그램 사이의 효율적인 데이터 연동을 위해 나온 것으로 볼 수 있습니다. 다른 프로그램은 워드프레스를 포함한 PHP 또는 다른 언어로 만든 프로그램을 말하며, 이 프로그램들은 자바스크립트를 많이 사용합니다.

워드프레스는 자바스크립트를 사용하는 프로그램과 데이터를 교환하기 위해서 개방형 표준 데이터 형식으로 부르는 JSON^{JavaScript Object Notation}을 사용합니다. 워드프레스로 데이터를 요청하면 JSON 형식의 데이터로 반환하여 제공한다는 뜻입니다.

결국, 워드프레스 REST API는 원격에서 다른 프로그램이나 시스템의 요청이 있을 때 JSON 형식으로 워드프레스 사이트 데이터를 제공하는 사전 정의된 데이터 서비스 정도로 요약할 수 있습니다. 사전 정의된 것이라도 사용자가 추가 정의할 수 있으며, 워드프레스 REST API는 워드프레스에서 사용 또는 제공하는 REST API라는 정도의 넓은 범주에서 이해하면 됩니다.

REST API 사용에 관련한 키워드 중 일부를 아주 간략하게 짚어봅니다. 인터넷을 사용하는 사람은 누구나 하는 것으로 새로운 정보가 아니며, 기술 관점이 아닌 일반 행동에 초점을 두는 게 좋습니다.

HTTP 요청과 응답

워드프레스만이 아니라 REST 범주에서 늘 등장하는 기본 개념 중 ‘HTTP 요청’이 있습니다. 요청은 갑자기 나온 것이 아니라 웹브라우저 주소 입력란에 특정 주소를 입력하여 다시 웹브라우저 화면에서 결과를 보기 위한 단순한 행위를 말합니다. 이때 웹브라우저의 화면에 나타나는 결과는 서버의 ‘응답’입니다. 사람의 직접적 웹브라우저 주소 입력 행위만이 아니라 프로그래밍에 의한 행위도 마찬가지입니다.

HTTP methods

HTTP 요청은 몇 가지가 있는데 워드프레스를 예로 들면, 사용자가 특정 싱글 포스트를 보기 위해 해당 URL을 웹브라우저에 입력하는 것은 GET(R) 요청, 새로운 포스트를 작성 후 등록하는 것은 POST(C) 요청, 공개한 특정 포스트를 편집 화면에서 수정 후 업데이트하는 것은 PUT(U) 요청, 등록한 포스트를 삭제하는 것은 DELETE(D) 요청입니다.

CRUD

앞에서 예를 든 4가지(HTTP methods)의 요청을 보통 ‘CRUD’로 부르며, 데이터를 다루는 기본 행위를 뜻합니다. 앞에서 괄호에 표기한 대문자를 붙여 표기한 것이며, 데이터 처리의 기준에서 다음의 용어로 HTTP methods와 함께 나타낼 수 있습니다.

• C : Create (POST)
• R : Read (GET)
• U : Update (PUT)
• D : Delete (DELETE)

HTTP method는 사용의 문제이므로 깊은 이해가 필요하지 않고, 권한 제어나 보안 측면을 생각하여 특정 요청 제한 등의 설정이 필요하다는 정도만 기억하면 됩니다.

Routes, endpoints

‘라우트’는 URI 또는 URI 일부를 뜻하며, ‘엔드포인트’는 서버에서 받은 응답으로 다르게 말하면 ‘요청 내용’입니다. 라우트와 엔드포인트도 개념의 이해가 아니라 사용 경험으로 이해하는 게 좋습니다. 반복해서 말하지만, 개념에 치중하면 사용이 어려워 결국 개념에 머무르게 되므로 워드프레스 REST API 포함 워드프레스 전체에 걸쳐 ‘사용 경험’을 선행할 것을 권장합니다.

워드프레스 REST API 기본 요소를 말할 때 스키마^Schema와 REST API 요청, 응답, 컨트롤러^Controller 클래스도 포함하지만, 특정 기능 또는 프로그램 개발에 필요할 때 학습하면 됩니다. 간단한 사용자 정의 라우트나 엔드포인트에도 필요할 수 있지만, 보통은 워드프레스 기본 제공 상태만으로 충분합니다.

둘러보기

REST API 사용은 JSON 형식의 데이터를 구하는 것이 목적이므로, JSON 데이터를 웹브라우저에서 쉽게 알아볼 수 있는 확장 프로그램을 설치하여 구성 과정에 도움을 얻는 것이 좋습니다. 다음 목록의 크롬 확장프로그램과 애플리케이션을 설치합니다. 설치 방법은 따로 안내하지 않습니다.

• JSONView
• POSTMAN

위 목록의 두 번째 ‘POSTMAN’ 애플리케이션은 많이 알려진 프로그램으로 풍부한 기능이 있으므로 웹브라우저 확장 프로그램보다 더 유용할 수 있습니다.

네임스페이스, 라우트, 엔드포인트 인덱스

다음 목록의 주소를 브라우저에 각각 입력하여 결과(응답)를 확인해보세요. 첫 번째 주소를 브라우저에 입력하면 현재 워드프레스 예제 사이트의 네임스페이스를 포함한, 사용할 수 있는 라우트와 엔드포인트 등의 전체 목록을 볼 수 있습니다.

• localhost/wp-json/
• localhost/wp-json/wp/v2

위의 주소에서 /wp-json/ 경로는 워드프레스 REST API 자체의 기본 경로(path)이므로 특정 라우트에 포함하지 않습니다. 도메인과 이 경로를 포함한 URL을 구할 때 다음 함수를 사용할 수 있습니다.

rest_url();
esc_url_raw( rest_url() ); // 주로 사용
get_rest_url();

특정 라우트를 포함할 때 다음처럼 사용하면 됩니다.

esc_url_raw( rest_url( 'wp/v2/posts' ) );
// 결과 - http://localhost/wp-json/wp/v2/posts

리소스와 기본 라우트

워드프레스는 기본 포스트 타입과 분류, 사용자, 코멘트, 사이트 설정 등의 구성 요소에 따른 기본 라우트를 제공합니다. 다음은 기본 라우트를 포함한 워드프레스 REST URL 일부입니다. 각 주소를 브라우저에 입력하여 REST API가 제공하는 데이터를 확인해보세요. 어떤 데이터를 제공하는지 가볍게 둘러보세요.

• localhost/wp-json/wp/v2/posts
• localhost/wp-json/wp/v2/pages
• localhost/wp-json/wp/v2/media
• localhost/wp-json/wp/v2/taxonomies

위의 목록에서 마지막은 워드프레스 사이트에 정의된 분류(taxonomy) 자체 데이터의 REST URL인데, 각 분류의 하위 term 데이터는 나오지 않습니다. 특정 분류, 예를 들어 category와 mediacat 분류의 하위 term 데이터를 요청하려면 다음 목록처럼 사용하면 됩니다.

• localhost/wp-json/wp/v2/categories
• localhost/wp-json/wp/v2/mediacat

커스텀 포스트 타입

사이트에 존재하는 포스트 타입 자체에 관한 데이터를 요청하려면 다음 주소로 가능합니다. 정확하게 말하면 REST API 허용 포스트 타입입니다.

• localhost/wp-json/wp/v2/types

그런데, 결과를 보면 예제 사이트에서 추가 정의한 pic_album 포스트 타입에 관한 데이터는 나오지 않습니다. 다음 주소로 해당 포스트 타입의 포스트 데이터를 요청해도 이어서 나오는 그림처럼 404 응답 코드를 출력합니다.

• localhost/wp-json/wp/v2/pic_album

이유는 다음 코드에서 찾을 수 있습니다.

// wp-content/mu-plugins/pics-tax-cpt.php 파일 125번 줄
'show_in_rest' => false

위의 코드에서 false를 true로 변경하면 pic_album 포스트 타입의 포스트 데이터를 얻을 수 있으며, REST API 허용 사이트 포스트 타입에도 추가됩니다. 기본이며 간단하게 true 설정만으로 거의 모든 것이 가능합니다.

싱글 포스트

예를 들어, 특정 아이디의 post 타입 포스트와 attachment 타입 포스트(media)는 각각 다음 목록의 주소로 요청하면 됩니다. 아이디는 필자와 다를 수 있습니다.

• localhost/wp-json/wp/v2/posts/454
• localhost/wp-json/wp/v2/media/414

파라미터

예제는 attachment 타입 포스트 중심이므로 다음처럼 media 라우트에 파라미터를 추가하여 이미지 포스트 응답을 확인해봅니다. 목록의 숫자는 사진(11), 여행(328), PhotoWoman(13)을 뜻하는 것으로 필자와 다를 수 있습니다.

• localhost/wp-json/wp/v2/media?author=13
• localhost/wp-json/wp/v2/media?mediacat=11
• localhost/wp-json/wp/v2/media?mediacat=11&photocat=328
• localhost/wp-json/wp/v2/media?search=바다
• localhost/wp-json/wp/v2/media?mediacat=11&photocat=328&search=바다
• localhost/wp-json/wp/v2/media?mediacat=11&photocat=328&search=바다&author=13

위 목록의 응답을 사이트의 검색 결과와 비교하면 같습니다. 이때 응답은 기본으로 한 페이지에 10개, 최대 100개입니다. 웹브라우저에서 확인하려면 개발자 도구의 Headers 정보를 확인하면 됩니다. 앞에서 설치한 POSTMAN 애플리케이션을 사용하면 쉽게 확인할 수 있습니다.

다음 목록을 참고하세요.

• localhost/wp-json/wp/v2/media?page=2
• localhost/wp-json/wp/v2/media?per_page=20
• localhost/wp-json/wp/v2/media?page=2&per_page=20
• localhost/wp-json/wp/v2/media?page=2&per_page=20&order=desc
• localhost/wp-json/wp/v2/media?mediacat=11&page=2&per_page=20&order=desc

워드프레스 REST API 관련한 기본 내용은 이 정도면 충분하며, 메타 데이터와 사용자 정의 및 인증에 관련한 내용은 나중에 예제 사이트 구성 과정에서 간략하게 살펴봅니다.

간단한 예제

앞에서 워드프레스 REST API 기초에 관하여 간략하게 살펴봤지만, 처음 경험할 때 실제 사이트에 적용하는 방법을 가늠하기 어려울 수 있습니다. 예제 사이트에 적용하기 전에 아주 간단한 예제로 경험해봅니다. 먼저, 다음 파일을 예제 사이트와 관련이 없는 PC의 적당한 위치에 받고 압축을 풉니다.

편집기로 index.html, wprestapi.js 파일을 엽니다. 그리고, 브라우저로 index.html 파일을 실행(열기)하여 다음 그림의 화면이 나오는지 확인합니다.

제공한 파일은 ‘응답하라’ 버튼(#btn)을 클릭할 때 예제 사이트의 포스트를 출력(#postlist)하는 것으로 세부 내용은 wprestapi.js 파일에 정의되어 있습니다. 버튼이 사라질 때까지 클릭해보세요.

먼저 짚어야 하는 것은 워드프레스를 설치한 예제 사이트 외부에서 워드프레스 사이트의 데이터를 요청한다는 것입니다. 예제 사이트는 로컬 서버에 설치하였지만, 브라우저에서 실행한 index.html 파일에서 보면 원격의 워드프레스에 요청한 것과 같습니다. 자신의 워드프레스 사이트가 있고 인증이 없어도 가능한 REST API를 제공하고 있다면 로컬 파일에 정의하여 사이트에 직접 접근하지 않아도 포스트를 볼 수 있습니다.

다시 브라우저에서 개발자 도구를 실행(F12)하고, Console 탭으로 이동한 후 예제 페이지를 새로 고칩니다. 그리고, 버튼이 사라질 때까지 클릭하여 다음 그림의 결과를 확인합니다. 그림의 포스트는 실제 결과와 다를 수 있습니다.

위의 그림 Console 로그는 편집기의 wprestapi.js 파일 11번 줄에 의한 것으로 REST API 요청 응답 확인 과정에서 자주 사용하는 것이며, 브라우저의 가시적 결과와 같이 확인하여 이해를 돕기 위해 추가하였습니다.

편집기의 wprestapi.js 2, 3번 줄을 다음으로 변경하고 저장한 후 브라우저 예제 페이지를 새로 고쳐 버튼이 사라질 때까지 클릭해보세요.

var rest_url = 'http://localhost/wp-json/wp/v2/media?';
var pageCounter = 1, perPage = 50;

자바스크립트 코드는 따로 설명하지 않으므로 결과로 경험하는 것에 초점을 두기 바랍니다. 제공한 파일의 코드는 최소한의 경험을 위해 예제 사이트 기준으로 구성한 것이므로 설정에 따라 오류가 발생할 수 있습니다.