WordPress REST API là giao diện để phần mềm khác đọc và ghi nội dung của website WordPress bằng dữ liệu JSON, thông qua các địa chỉ gọi là endpoint. Bài viết, trang, ảnh, chuyên mục và thẻ đều có endpoint riêng, nằm dưới đường dẫn /wp-json/wp/v2/. Theo tài liệu chính thức của WordPress, chính API này đứng sau trình soạn thảo khối, và cũng là cách để một ứng dụng bên ngoài như trang Next.js hay app di động lấy nội dung từ WordPress mà không cần đi qua giao diện mặc định của theme.
Bài này trả lời ba câu hỏi người làm website hay hỏi khi bắt đầu: endpoint nào cần biết, tham số nào quyết định kết quả trả về, và làm sao gọi thử để thấy dữ liệu thật trước khi viết một dòng mã ứng dụng. Mọi tên endpoint và tham số lấy từ tài liệu chính thức của WordPress, kiểm ngày 13/10/2026. Ví dụ gọi thử chạy trên site demo công khai wordpress.org/news, cũng kiểm cùng ngày.
REST API của WordPress làm được gì
REST API là một tập quy ước để truy cập dữ liệu dưới dạng tài nguyên, mỗi tài nguyên là một địa chỉ URL và mỗi lần gọi trả về một đối tượng JSON. Tài liệu của WordPress mô tả đây là cách để ứng dụng gửi và nhận dữ liệu trên site, và JSON được hầu hết ngôn ngữ lập trình đọc được, nên vì vậy cùng một site có thể phục vụ trình duyệt, app di động và công cụ dòng lệnh.
Điểm người làm website cần hiểu sớm là API này không mở thêm quyền cho ai. Tài liệu ghi rõ nội dung công khai trên site thường truy cập được qua API mà không cần đăng nhập. Bài viết riêng tư, bài có mật khẩu, người dùng nội bộ, loại nội dung tuỳ chỉnh và metadata chỉ lộ ra khi có xác thực, hoặc khi site chủ động cho phép. Vì vậy một ứng dụng bên ngoài không tự nhiên đọc được bản nháp của biên tập viên.
Trong thực tế, REST API thường được dùng cho ba việc. Thứ nhất là hiển thị nội dung WordPress ở nơi khác, ví dụ trang bán hàng viết bằng React hoặc Next.js, hoặc màn hình tin tức trong app. Thứ hai là đồng bộ bài viết và ảnh sang hệ thống khác, như kho dữ liệu, công cụ tìm kiếm nội bộ hay công cụ gửi bản tin. Thứ ba là tự tạo công cụ quản trị riêng, chẳng hạn một màn hình duyệt bài nằm ngoài wp-admin. Với một trang tin đơn giản chạy bằng theme mặc định, việc không dùng API vẫn hợp lý, nếu chưa rõ WordPress vận hành thế nào thì WordPress là gì và khi nào đủ dùng là điểm bắt đầu, và tài liệu cũng nói rõ không cần REST API để làm theme hay plugin WordPress.
Từ phiên bản nào thì API có sẵn trong WordPress
Lịch sử phiên bản ở đây dễ nhầm, do đó cần đọc đúng nguồn. Theo phần Discovery trong tài liệu chính thức, WordPress từ 4.4 đã bật hạ tầng API cho mọi site, nhưng lúc đó chưa có các endpoint lõi dưới namespace wp/v2. Các endpoint lõi như bài viết, trang, ảnh và chuyên mục được thêm từ WordPress 4.7. Vì vậy, với site chạy phiên bản trước 4.7 và không cài plugin REST API, namespace wp/v2 sẽ không có mặt trong chỉ mục.
Cách kiểm nhanh nhất là mở địa chỉ gốc /wp-json/ của site. Trong phần trả về có mục “namespaces”, và nếu thấy wp/v2 trong danh sách thì site đã có các endpoint lõi. Với những site đang chạy WordPress hiện đại, đây là trường hợp gần như chắc chắn, nhưng việc kiểm tra mất vài giây, đáng làm trước khi viết mã.
Các endpoint cần biết
Mọi endpoint lõi đều nằm dưới namespace wp/v2. Bảng dưới đây liệt kê 8 endpoint người làm website gặp nhiều nhất, theo trang tham chiếu của WordPress kiểm ngày 13/10/2026.
| Endpoint | Dữ liệu trả về | Ghi chú khi dùng |
|---|---|---|
| /wp/v2/posts | Danh sách bài viết | Mặc định chỉ trả bài ở trạng thái publish |
| /wp/v2/pages | Danh sách trang tĩnh | Có thêm /wp/v2/pages/<id>/revisions cho các bản đã lưu |
| /wp/v2/media | Ảnh và tệp đính kèm | Dùng để lấy đường dẫn ảnh đại diện và ảnh trong bài |
| /wp/v2/categories | Chuyên mục | Bài viết lưu ID chuyên mục, cần gọi thêm để đổi ra tên |
| /wp/v2/tags | Thẻ | Cấu trúc giống chuyên mục |
| /wp/v2/taxonomies | Danh sách taxonomy của site | Cho biết site có những nhóm phân loại nào |
| /wp/v2/types | Danh sách loại nội dung | Liệt kê post, page và loại tuỳ chỉnh đã đăng ký |
| /wp/v2/comments | Bình luận | Dùng khi đồng bộ hoặc kiểm duyệt bình luận |
Ngoài nhóm trên, trang tham chiếu còn có users, settings, block-types, blocks và block-renderer. Bài này không đi sâu vào các endpoint đó, vì đa số dự án nội dung chỉ cần bài viết, trang, ảnh và phân loại. Điểm cần nhớ là tên endpoint luôn số nhiều, ví dụ /wp/v2/posts chứ không phải /wp/v2/post, và đường dẫn đầy đủ luôn có tiền tố site, ví dụ https://example.com/wp-json/wp/v2/posts.
Các tham số quyết định dữ liệu trả về
Gọi /wp/v2/posts không kèm tham số chỉ cho ra một trang bài với mặc định của WordPress. Muốn lấy đúng thứ cần dùng, người làm website phải điều chỉnh tham số. Bảng sau gom 10 tham số hay dùng nhất, giá trị mặc định lấy từ trang tham chiếu của endpoint posts.
| Tham số | Mặc định | Giá trị hợp lệ hoặc ý nghĩa | Ví dụ |
|---|---|---|---|
| page | 1 | Số trang cần lấy | page=2 |
| per_page | 10 | Từ 1 đến 100 bản ghi mỗi lần | per_page=100 |
| offset | Không có | Bỏ qua một số bản ghi đầu | offset=6 |
| order | desc | asc hoặc desc | order=asc |
| orderby | date | Với posts: author, date, id, include, modified, parent, relevance, slug, include_slugs, title | orderby=title |
| status | publish | publish, future, draft, pending, private | status=draft |
| slug | Không có | Lọc theo một hoặc nhiều slug | slug=ten-bai-viet |
| search | Không có | Tìm theo chuỗi ký tự | search=mcp |
| _fields | Không có | Chỉ trả về các trường liệt kê | _fields=id,title,link |
| _embed | Không có | Nhúng luôn tài nguyên liên kết như tác giả, thẻ, ảnh | _embed=author |
Hai tham số tiết kiệm nhiều nhất là _fields và _embed. Tài liệu về tham số chung ghi rằng khi có _fields, WordPress bỏ qua việc tính toán các trường không cần, vì thế phản hồi nhỏ hơn và tải nhanh hơn. Từ WordPress 5.3, _fields còn hỗ trợ trường lồng nhau trong meta. Tham số _embed từ WordPress 5.4 có thể giới hạn danh sách quan hệ cần nhúng, thay vì nhúng tất cả. Muốn dùng _embed cùng _fields thì phải đưa cả _links và _embedded vào danh sách trường, nếu không phản hồi sẽ thiếu phần nhúng.
Tham số status cần đọc kỹ. Mặc định chỉ có publish. Các trạng thái draft, pending và private thuộc về nội dung chưa công khai, thường không được trả về cho người gọi chưa đăng nhập. Phần dưới bài sẽ có ví dụ cụ thể.
Phân trang: đọc tổng số để biết còn trang nào
Một site có hàng nghìn bài không thể lấy hết trong một lần gọi. WordPress giới hạn per_page ở mức 100, và tài liệu phân trang nói rõ giới hạn này để tránh làm chậm site. Muốn có toàn bộ danh sách, ứng dụng phải gọi nhiều lần, tăng page lên từng bước và ghép kết quả lại.
Điều giúp việc này gọn là header phản hồi. Mỗi phản hồi có danh sách bản ghi kèm hai header: X-WP-Total cho biết tổng số bản ghi trong bộ sưu tập, và X-WP-TotalPages cho biết tổng số trang. Ứng dụng không cần đoán khi nào dừng. Chỉ cần đọc X-WP-TotalPages rồi lặp đến trang cuối.
Lúc kiểm, trên site demo wordpress.org/news, số bài là 1110, tức 555 trang khi mỗi trang có hai bài. Ở mức 100 bài mỗi trang, cùng bộ dữ liệu đó sẽ cần 12 lần gọi. Con số này thay đổi theo thời gian vì site vẫn đăng bài, ứng dụng không ghi cứng tổng số vào mã.
Gọi thử bằng curl trước khi viết mã
Cách học nhanh nhất là gọi thử từ dòng lệnh, xem dữ liệu thật rồi mới đưa vào ứng dụng. Ví dụ dưới đây chạy trên site demo công khai wordpress.org/news, chỉ để minh hoạ cách đọc kết quả. Với site khác, chỉ cần thay tên miền. Các bước theo thứ tự:
- Kiểm site có API hay không. Mở địa chỉ https://wordpress.org/news/wp-json/ và tìm wp/v2 trong mục “namespaces”. Có wp/v2 nghĩa là các endpoint lõi đã sẵn sàng.
- Gọi danh sách bài đơn giản kèm header: curl -i “https://wordpress.org/news/wp-json/wp/v2/posts?per_page=2”. Tham số -i giúp thấy cả X-WP-Total và X-WP-TotalPages trong phần đầu phản hồi.
- Thu gọn trường trả về: thêm &_fields=id,date,slug,link,title vào cuối đường dẫn. Phản hồi chỉ còn năm trường, và kích thước giảm rõ rệt.
- Đọc header phân trang trong phản hồi để biết số trang. Với demo, per_page=2 cho X-WP-TotalPages là 555 khi kiểm ngày 13/10/2026.
- Sang trang tiếp theo: thêm &page=2 vào đường dẫn, rồi so sánh id của hai bản ghi đầu để chắc rằng không bị trùng.
- Thử vượt giới hạn: gọi per_page=101. Demo trả về mã 400 kèm thông báo “per_page must be between 1 (inclusive) and 100 (inclusive)”. Ứng dụng cần bắt lỗi này và xử lý, không nên để người dùng cuối thấy.
- Thử lấy bản nháp không đăng nhập: gọi status=draft. Demo trả về lỗi “rest_invalid_param” với nội dung “Status is forbidden”, nghĩa là cần xác thực mới được đọc trạng thái này.
Sau bước cuối, người làm website đã biết ba điều quan trọng: site có API hay không, bộ dữ liệu có bao nhiêu trang, và trạng thái nào bị khoá với khách không đăng nhập. Ba điều này quyết định phần lớn thiết kế của ứng dụng gọi API.
Trạng thái công khai và riêng tư
Trường status của bài viết có 5 giá trị trong tài liệu schema: publish, future, draft, pending và private. Publish là bài đã đăng và hiển thị công khai. Future là bài đặt lịch, sẽ đăng vào thời điểm định sẵn. Draft là bản nháp, pending là bài đang chờ duyệt, và private là bài chỉ hiện với người có quyền xem.
Khi ứng dụng bên ngoài gọi API không kèm xác thực, chỉ có bài publish là lộ ra một cách hợp lệ. Tài liệu cũng cho biết cơ chế xác thực trong API giữ nguyên quyền của WordPress, nên một bài private không thể đọc chỉ vì ứng dụng biết ID của nó. Điều này giúp an toàn, nhưng cũng có một hệ quả: nếu ứng dụng cần xem bản nháp để duyệt, nó phải có tài khoản và xác thực đúng cách.
Về xác thực, tài liệu mô tả hai hướng. Cookie kèm nonce với header X-WP-Nonce chỉ dùng được khi đoạn mã chạy ngay trong WordPress với người dùng đã đăng nhập. Với ứng dụng bên ngoài, hướng được tài liệu khuyến nghị là Application Passwords, có từ WordPress 5.6. Người quản trị tạo mật khẩu ứng dụng trong trang sửa người dùng, rồi ứng dụng dùng xác thực Basic với mật khẩu đó. Mật khẩu này là khoá riêng cho ứng dụng, tách khỏi mật khẩu đăng nhập của người quản trị, nên không cần đưa mật khẩu đăng nhập vào mã của dịch vụ bên ngoài.
Vì sao ứng dụng ngoài dựa vào REST API
Lý do lớn nhất là tách phần nội dung khỏi phần hiển thị. WordPress vẫn là nơi biên tập viên viết, sửa và duyệt bài bằng giao diện quen thuộc. Phần hiển thị thì nằm ở ứng dụng riêng, viết bằng công nghệ phù hợp với tốc độ và trải nghiệm mong muốn. Ứng dụng chỉ cần đọc JSON từ API, không phải kéo theo cả theme và plugin của WordPress vào giao diện cuối.
Với kiến trúc này, cùng một nguồn nội dung có thể phục vụ nhiều đầu ra: trang web, app di động, màn hình quảng cáo hoặc một kênh chatbot. Mỗi đầu ra đọc đúng trường cần thiết nhờ _fields, và mỗi đầu ra tự phân trang theo X-WP-TotalPages. Khi một đầu ra thay đổi, nguồn nội dung không phải sửa.
Đổi lại, kiến trúc này đòi hỏi một lớp kết nối được kiểm thử kỹ. Khi ứng dụng cần nhận sự kiện từ bên thứ ba, webhook thanh toán và cách tích hợp là một cách khác để nhận dữ liệu, còn phần kết nối cổng thanh toán nằm ở tích hợp cổng thanh toán vào phần mềm qua API. Phải quản lý đường dẫn ảnh, cache, lỗi mạng, bản nháp và quyền xem. Với các site lớn, đây là chỗ dễ phát sinh nhiều vấn đề nhất. Với ứng dụng nội bộ có quy trình riêng, dịch vụ lập trình web app là hướng khác. Nếu việc cần làm là chuyển nội dung WordPress sang một giao diện riêng, dịch vụ lập trình website headless WordPress của MONA bao gồm phần kết nối này, và bài so sánh headless WordPress với WordPress thường giải thích chi tiết hơn các đánh đổi trước khi quyết định.
Hỏi đáp
REST API có sẵn trong mọi bản WordPress không?
Không hoàn toàn. Theo tài liệu chính thức, từ 4.4 WordPress đã bật hạ tầng API, nhưng các endpoint lõi dưới wp/v2 chỉ có từ 4.7. Site cũ hơn cần được nâng cấp, hoặc cài plugin REST API, thì mới có đầy đủ endpoint. Việc kiểm tra bằng mục namespaces ở địa chỉ /wp-json/ cho kết quả chắc chắn nhất.
Muốn lấy toàn bộ bài viết thì phải gọi bao nhiêu lần?
Số lần gọi bằng số trang trong X-WP-TotalPages. Với per_page=100, một site có 1.110 bài cần 12 lần gọi, số liệu đo trên demo ngày 13/10/2026. Ứng dụng đọc X-WP-TotalPages trong phản hồi đầu tiên thay vì tự tính, vì số trang thay đổi khi site đăng thêm bài.
Vì sao bản nháp không hiện khi gọi API không đăng nhập?
Vì tham số status mặc định là publish. Gọi status=draft không có xác thực sẽ bị từ chối với thông báo “Status is forbidden”. Đây là hành vi đúng: nội dung chưa công khai chỉ đọc được khi có quyền. Muốn xem bản nháp từ ứng dụng, dùng xác thực bằng Application Passwords của tài khoản có quyền xem nội dung đó.
Viết theme hay plugin có bắt buộc dùng REST API không?
Không. Tài liệu chính thức nói rõ không cần dùng REST API để làm theme hay plugin. API cần thiết khi đoạn mã chạy ở phía trình duyệt viết bằng JavaScript, hoặc khi ứng dụng là một chương trình độc lập viết bằng ngôn ngữ khác PHP. Nếu site đã chạy tốt bằng cơ chế thông thường, không cần thêm API chỉ để có API.
Ứng dụng ngoài nên dùng cookie hay Application Passwords?
Với ứng dụng bên ngoài, Application Passwords là hướng tài liệu chỉ ra, vì cookie chỉ có hiệu lực khi đoạn mã chạy trong WordPress với người dùng đã đăng nhập. Mật khẩu ứng dụng được tạo riêng cho từng dịch vụ và không cần đến mật khẩu đăng nhập chính. Không đưa mật khẩu đăng nhập thật vào mã nguồn của ứng dụng.
Nếu việc cần làm là kéo nội dung WordPress về một ứng dụng riêng, hoặc tách giao diện khỏi WordPress mà vẫn giữ biên tập viên quen tay, MONA nhận dựng phần kết nối và giao diện đó. Gọi hotline 1900 636 648 để trao đổi phạm vi, nguồn dữ liệu và thời gian làm.
