Đưa custom post type và trường tùy chỉnh ra REST API bằng show_in_rest

Custom post type (CPT) là kiểu nội dung do đội kỹ thuật tự tạo, ví dụ dự án, sản phẩm hay nhân sự. Mặc định, CPT không xuất hiện trên REST API của WordPress, dù nó có thể đã hiện đầy đủ trong màn hình quản trị. Muốn ứng dụng bên ngoài đọc hoặc ghi được, phải khai báo show_in_rest cho CPT, và làm tương tự cho taxonomy cùng từng trường meta cần lộ ra.

Nếu chưa rõ WordPress là gì và khi nào site đủ dùng, xem WordPress là gì, khi nào đủ dùng. Bài này đi lần lượt qua ba chỗ cần khai báo, đưa một đoạn PHP tối thiểu đặt trong plugin, rồi chỉ cách kiểm bằng một lệnh GET. Tên tham số, giá trị mặc định và phiên bản đều lấy từ trang tham chiếu của WordPress và tài liệu của ACF, tra ngày 13/10/2026. Trình tự trong bài đi từ CPT xuống taxonomy rồi đến meta, mỗi tầng có một lần kiểm riêng, để khi lỗi xảy ra thì biết nó nằm ở tầng nào. Nếu đội kỹ thuật đang dựng website WordPress làm nguồn nội dung cho một giao diện riêng, bước này thường là việc đầu tiên, xem thêm headless WordPress khác WordPress thường ở đâu.

Khai báo show_in_rest khi đăng ký CPT

Hàm register_post_type() phải được gọi trên hook init. Trang tham chiếu khuyên đừng gắn đăng ký post type trước hook này. Tham số show_in_rest có mặc định là false, vì vậy một CPT đăng ký đủ mà không khai báo vẫn kín với REST, dù nó đã hiện đầy đủ trong trang quản trị. Trang changelog ghi tham số này có từ WordPress 4.7.0, nghĩa là với bản từ 4.7.0 trở lên, khai báo này có sẵn trong lõi và không cần cài thêm plugin.

Bảng dưới liệt kê bốn tham số liên quan tới REST, đúng theo mô tả trên trang tham chiếu.

Với rest_base, nếu để mặc định thì đường dẫn trùng tên CPT. Khoá của CPT phải viết thường, không quá 20 ký tự, chỉ gồm chữ không dấu, số, dấu gạch ngang và gạch dưới, theo mô tả của trang tham chiếu. Ví dụ trong bài này dùng namespace mặc định wp/v2. Tài liệu REST API handbook lấy ví dụ CPT book đặt rest_base là books, để đường dẫn thành số nhiều. Việc đổi rest_base cần làm trước khi có ứng dụng nào gọi, vì sau khi đổi, đường dẫn cũ không còn là đường dẫn của CPT.

Đưa taxonomy ra REST API bằng register_taxonomy

Taxonomy là cách phân nhóm bài, ví dụ “Loại dự án” gồm website, phần mềm và ứng dụng di động. Hàm register_taxonomy() có bộ tham số giống CPT: show_in_rest mặc định là false, rest_base mặc định là tên taxonomy, rest_controller_class mặc định là WP_REST_Terms_Controller. Hàm này cũng không được gọi trước hook init, theo ghi chú của trang tham chiếu, nên người làm thường đặt đăng ký taxonomy ngay cạnh đăng ký CPT để dễ đọc.

Trong ví dụ của handbook, taxonomy genre được gắn vào CPT book, và cả hai đều bật show_in_rest. Cặp khai báo này cần kiểm cùng lúc: gọi GET tới đường dẫn của CPT rồi tới đường dẫn của taxonomy, sau đó đối chiếu từng kết quả với trang quản trị. Nếu một trong hai đường dẫn trả lỗi, phần còn thiếu sẽ lộ ra ngay trong bước kiểm này.

Đưa trường meta ra REST API bằng register_post_meta

Trường tùy chỉnh được lưu dưới dạng meta. Trang register_post_meta() ghi rằng hàm này nhận cùng tham số với register_meta(), và hàm được thêm từ bản 4.9.8. Ba điều cần nhớ khi lộ meta ra REST: show_in_rest mặc định là false, CPT phải khai báo hỗ trợ custom-fields, và auth_callback quyết định ai được ghi.

Với kiểu array, show_in_rest không thể chỉ là true, vì trang register_meta() yêu cầu khai báo schema cho từng phần tử của mảng. Thiếu schema, WordPress ghi nhận lỗi dùng sai hàm và trường không được đăng ký đúng cách. Các kiểu đơn giản như string, integer hay boolean chỉ cần true. Trang tham chiếu có ví dụ riêng cho trường mảng, và đội kỹ thuật nên đọc kỹ ví dụ đó trước khi lộ một trường mảng ra ngoài.

Về quyền ghi, trang register_meta() ghi rằng auth_callback được gọi khi kiểm tra các quyền trên. Khi bỏ trống, WordPress coi khoá có dấu gạch dưới ở đầu là khoá bảo vệ và từ chối ghi, còn khoá thường thì được cho phép. Vì vậy, trường chứa dữ liệu nhạy cảm như số tiền hợp đồng hay ghi chú nội bộ cần có auth_callback riêng, do đội kỹ thuật viết và kiểm, thay vì dựa vào mặc định của WordPress. Đây là chỗ dễ sót nhất.

Đoạn mã PHP tối thiểu để đặt trong plugin

Đoạn dưới đăng ký CPT project, taxonomy project_type và trường client_budget. Đặt trong một plugin riêng sẽ dễ kiểm và dễ tắt hơn là thêm vào functions.php của theme. Hàm kích hoạt gọi lại các hàm đăng ký trước khi làm mới quy tắc đường dẫn, vì flush chỉ nhìn thấy những post type đã được đăng ký tại thời điểm đó. Đoạn mã dưới đây đã kiểm cú pháp PHP.

<?php
/**
 * Plugin Name: MONA demo REST cho CPT
 */

// Register the "project" custom post type and expose it in the REST API.
add_action( 'init', 'mona_demo_register_project' );

function mona_demo_register_project() {
	register_post_type(
		'project',
		array(
			'labels'       => array(
				'name'          => 'Dự án',
				'singular_name' => 'Dự án',
			),
			'public'       => true,
			'show_in_rest' => true,     // Create the route, default is false.
			'rest_base'    => 'du-an',  // URL segment: /wp-json/wp/v2/du-an
			'supports'     => array( 'title', 'editor', 'custom-fields' ), // Needed for meta in REST.
		)
	);
}

// Register the "project_type" taxonomy and expose its terms in the REST API.
add_action( 'init', 'mona_demo_register_project_type', 30 );

function mona_demo_register_project_type() {
	register_taxonomy(
		'project_type',
		array( 'project' ),
		array(
			'label'        => 'Loại dự án',
			'hierarchical' => true,
			'show_in_rest' => true,          // Create the terms route.
			'rest_base'    => 'loai-du-an',
		)
	);
}

// Register the "client_budget" meta field and expose it in REST responses.
add_action( 'init', 'mona_demo_register_meta' );

function mona_demo_register_meta() {
	register_post_meta(
		'project',
		'client_budget',
		array(
			'type'          => 'integer',
			'single'        => true,
			'show_in_rest'  => true,     // Value appears under the "meta" key.
			// Decide who may write the value. Here: users who can edit the post.
			'auth_callback' => function ( $allowed, $meta_key, $post_id ) {
				return current_user_can( 'edit_post', $post_id );
			},
		)
	);
}

// Flush rewrite rules when the plugin is activated, so the new routes work.
register_activation_hook( __FILE__, 'mona_demo_activate' );

function mona_demo_activate() {
	mona_demo_register_project();
	mona_demo_register_project_type();
	flush_rewrite_rules();
}

// Flush again on deactivation, so the old rules are removed.
register_deactivation_hook( __FILE__, 'flush_rewrite_rules' );

Tài liệu REST API handbook cũng có ví dụ tối thiểu tương tự, đăng ký CPT book với show_in_rest bật true.

Thứ tự làm để gọi được API

1. Chọn slug CPT và rest_base trước khi đăng ký. Đổi sau khi đã có ứng dụng gọi sẽ phải sửa lại mọi nơi trỏ tới đường dẫn cũ.
2. Thêm show_in_rest vào register_post_type() trước, vì đó là bước tạo route cho CPT. Sau đó mới thêm show_in_rest và rest_base cho taxonomy đi kèm, để mỗi bước kiểm được riêng.
3. Nếu cần lộ meta, khai báo show_in_rest trong register_post_meta() và thêm custom-fields vào danh sách hỗ trợ của CPT.
4. Kích hoạt plugin. Nếu đã kích hoạt từ trước, vào Cài đặt, mục Đường dẫn tĩnh, rồi bấm Lưu để làm mới quy tắc.
5. Gọi GET tới đường dẫn REST và đối chiếu kết quả với dữ liệu trong trang quản trị.

Các bước trên làm được cả trên máy thử trước khi lên máy thật. Trên máy thử, chỉ cần một bản WordPress cài sẵn và thư mục plugin chứa file đã viết ở trên. Sau đó làm đúng thứ tự, đừng nhảy sang bước kiểm khi chưa làm mới quy tắc đường dẫn. Ghi lại kết quả của từng bước giúp khoanh vùng lỗi nhanh hơn khi có ứng dụng khác bắt đầu gọi vào. Kiểm xong mới đi tiếp.

Kiểm bằng GET trên đường dẫn REST

Lệnh dưới lấy năm dự án mới nhất. Thay example.com bằng domain thật của website.

curl -s "https://example.com/wp-json/wp/v2/du-an?per_page=5"

Kết quả là một mảng JSON, mỗi bài có id, title và slug. Nếu sau khi sửa bài mà trang hiển thị chưa đổi, xem sửa bài trên WordPress bao lâu thì trang đổi. Tham số per_page giới hạn số bài mỗi trang, nên khi thử với một CPT lớn, đội kỹ thuật nên đặt số nhỏ trước rồi mới tăng dần. Giá trị của trường đã khai báo show_in_rest nằm trong khoá meta của từng bài. Nếu thiếu khoá meta, hoặc khoá có nhưng không có client_budget, kiểm lại hai điều kiện: show_in_rest của trường có bật không, và CPT có hỗ trợ custom-fields không.

Khi cần kiểm riêng một bài, thêm id vào cuối đường dẫn, ví dụ /wp-json/wp/v2/du-an/123. Cách này cho kết quả của đúng bài đó, dễ đối chiếu với màn hình quản trị hơn là đọc cả danh sách. Thao tác POST cần xác thực, theo ghi chú trong tài liệu ACF, vì vậy lệnh GET ở đây chỉ dùng để kiểm đọc, không dùng để ghi.

Ba lỗi hay gặp khi đưa CPT ra REST API

• Đổi slug hoặc rest_base mà không làm mới quy tắc đường dẫn. Trang tham chiếu khuyến nghị gọi flush_rewrite_rules() trong hook kích hoạt và hủy kích hoạt khi đăng ký post type trong plugin. Nếu không làm, phải vào Cài đặt, mục Đường dẫn tĩnh và làm mới thủ công trước khi kiểm bất kỳ đường dẫn REST nào, vì nếu không sẽ khó biết lỗi đến từ khai báo hay từ quy tắc đường dẫn cũ.
• Meta không lộ dù đã đăng ký. Nguyên nhân thường là show_in_rest của trường vẫn là false, hoặc CPT không hỗ trợ custom-fields. Trang register_meta() nêu cả hai điều kiện.
• Ghi meta bị từ chối. Thường do khoá có dấu gạch dưới ở đầu, vì khoá đó bị coi là bảo vệ khi không có auth_callback, hoặc do auth_callback trả về false với tài khoản đang gọi. Kiểm lại auth_callback và quyền của tài khoản trước khi sửa phần còn lại.

Trường tùy chỉnh từ plugin như ACF khai báo thế nào

ACF là plugin tạo trường tùy chỉnh phổ biến trên WordPress. Theo tài liệu REST API chính thức của ACF, nhóm trường mặc định không hiện trên REST API. Phải bật “Show in REST API” trong mục Group Settings của từng nhóm trường, vì tài liệu ghi việc bật này thực hiện cho từng nhóm chứ không cho cả site một lần. Với CPT tạo trong ACF, mục REST API trong phần Advanced Configuration cho chỉnh khả năng hiện, namespace và lớp controller.

Dữ liệu trường ACF trả về trong một đối tượng acf của phản hồi GET. Đây là khác biệt cần nhớ khi đọc JSON: trường ACF nằm trong acf, còn meta đăng ký bằng register_meta() nằm trong meta, nên hai khoá này không thay thế được cho nhau. Trường đăng ký bằng code dùng register_post_meta(), còn trường tạo trong giao diện ACF dùng cài đặt của ACF. Chọn một cách cho mỗi trường để dễ bảo trì. Với filter acf/settings/rest_api_enabled trả về false, ACF tắt hẳn phần REST của mình, và mọi cài đặt Show in REST API trên từng nhóm trường sẽ không còn tác dụng.

Hỏi đáp

Đọc thêm

• WordPress REST API là gì? Các endpoint cần biết và cách gọi thử
• Xác thực WordPress REST API: Application Password, cookie nonce hay JWT
• WPGraphQL hay REST API cho WordPress: chọn theo việc cần làm