REST API và tài liệu API của ứng dụng

Đôi khi phần mềm khác cần dữ liệu của ứng dụng: trang web của đối tác liệt kê sản phẩm của bạn, một bảng tính kéo đơn hàng mới về, một ứng dụng di động, một công cụ tự động hóa như Zapier hay n8n. Chúng làm việc với ứng dụng qua một API — tập hợp các địa chỉ web (điểm cuối) trả về dữ liệu thay vì trang. REST API là loại phổ biến nhất.

MonstarX tạo API cho bạn mà không cần viết mã. Bạn chọn những gì muốn chia sẻ, và API hoạt động chỉ sau vài giây, kèm một trang tài liệu mà lập trình viên đọc được.

Tôi tìm thấy ở đâu?

Mở dự án, nhấp vào Quản trị trên thanh trên cùng, rồi nhấp API trong thanh bên của Quản trị. Bạn sẽ thấy API dự án: phía trên là thanh Tài liệu API dùng để xuất bản tài liệu API; bên trái là các điểm cuối, mỗi điểm cuối được đánh dấu Đang hoạt động hoặc Bản nháp; và bên dưới là Khóa API.

Làm sao để tạo một điểm cuối?

1. Trong Quản trị›API, nhấp vào Điểm cuối mới (hoặc dấu + bên cạnh Điểm cuối).

2. Chọn Bộ sưu tập — bảng mà điểm cuối làm việc cùng, như Công thức nấu ăn.

3. Chọn Thao tác:

   Thao tác	Phương thức và địa chỉ	Làm gì
   Liệt kê	GET /recipes	Trả về các bản ghi, mỗi lần một trang.
   Lấy	GET /recipes/{id}	Trả về một bản ghi theo id.
   Tạo	POST /recipes	Thêm một bản ghi.
   Cập nhật	PATCH /recipes/{id}	Thay đổi một số trường của bản ghi.
   Xóa	DELETE /recipes/{id}	Xóa một bản ghi.

4. Đặt Tên, Đường dẫn URL và, nếu muốn, Mô tả. Các thông tin này xuất hiện trong tài liệu API.

5. Trong Các trường cho phép truy cập, đánh dấu đúng những trường mà bên gọi được xem hoặc gửi. Trường nào không đánh dấu sẽ giữ riêng tư. Những trường có vẻ nhạy cảm, như mật khẩu và token, luôn bị loại ra.

6. Trong Truy cập, chọn ai được gọi (xem bên dưới).

7. Đánh dấu Xuất bản điểm cuối và nhấp vào Lưu và xuất bản điểm cuối. Điểm cuối đã xuất bản sẽ Đang hoạt động: trả lời yêu cầu ngay lập tức. Nếu bỏ trống ô này, Lưu điểm cuối giữ điểm cuối ở dạng Bản nháp.

   

Trong danh sách, mỗi điểm cuối ghi Đang hoạt động hoặc Bản nháp. Trạng thái này cũng hiện dưới Chỉnh sửa điểm cuối, kèm Thay đổi chưa lưu cho tới khi bạn lưu. Bỏ đánh dấu Xuất bản điểm cuối rồi lưu để tạm ngừng điểm cuối mà không xóa; Xóa sẽ xóa hẳn.

Ghi chú

Tạo, Cập nhật và Xóa thay đổi dữ liệu thật của bạn. Trước khi xuất bản một điểm cuối loại này, hãy bật thao tác tương ứng (thêm, sửa hoặc xóa) cho bảng đó trong phần cài đặt của bảng ở tab Quản trị. Xem Trang quản trị của ứng dụng.

Ai được gọi điểm cuối của tôi?

Truy cập	Ai được gọi	Áp dụng cho
Đọc công khai	Bất kỳ ai có địa chỉ.	Chỉ Liệt kê và Lấy
Khóa API dự án	Chỉ bên gọi gửi kèm một khóa API của dự án.	Mọi thao tác

Điểm cuối thay đổi dữ liệu luôn cần khóa.

Làm sao để tạo khóa API?

1. Trong Quản trị›API, nhấp vào Khóa API.

2. Nhập tên cho biết khóa sẽ được dùng ở đâu, như “Máy chủ tiện ích công thức”, rồi nhấp Tạo khóa.

3. Sao chép khóa ngay — khóa bắt đầu bằng mxapi_ và không thể hiện lại. Hãy cất ở nơi an toàn, như trình quản lý mật khẩu hoặc phần giá trị bí mật của dịch vụ kia.

Một khóa mở được mọi điểm cuối được bảo vệ bằng khóa trong dự án, nên hãy cấp cho mỗi dịch vụ một khóa riêng. Nhấp vào Thu hồi để tắt một khóa; mọi thứ đang dùng khóa đó ngừng hoạt động ngay lập tức.

Bên gọi gửi khóa trong header Authorization: Authorization: Bearer mxapi_….

Chú ý

Hãy giữ khóa API trên máy chủ. Khóa đặt trong trang web hay ứng dụng di động thì ai muốn xem cũng đọc được.

Làm sao để thử một điểm cuối?

Mở điểm cuối và nhấp vào Kiểm thử. Nhập ID bản ghi, Khóa Bearer hoặc Nội dung JSON nếu điểm cuối cần, rồi nhấp Gửi yêu cầu. Bạn sẽ thấy mã trạng thái (200 nghĩa là thành công), thời gian phản hồi và câu trả lời. Với điểm cuối cần khóa, hãy dán một khóa của bạn từ Khóa API vào Khóa Bearer.

Yêu cầu kiểm thử gửi tới điểm cuối thật, đang hoạt động, nên:

• Chưa thể kiểm thử bản nháp. Tab Kiểm thử ghi Điểm cuối này là một bản nháp; nhấp vào Lưu và xuất bản điểm cuối ngay tại đó để xuất bản rồi kiểm thử.
• Lưu thay đổi trước. Khi còn thay đổi chưa lưu, tab Kiểm thử yêu cầu bạn lưu trước khi kiểm thử, kèm nút Lưu điểm cuối.

Kiểm thử Tạo, Cập nhật hoặc Xóa sẽ thay đổi dữ liệu thật của bạn.

Tab Mã nguồn có sẵn lệnh cURL để sao chép, và tệp OpenAPI JSON để các công cụ API như Postman và Insomnia nhập vào.

Làm sao để xuất bản và chia sẻ tài liệu API?

Tài liệu API là một trang Tài liệu API dành cho lập trình viên: mọi điểm cuối đang hoạt động, các trường, có cần khóa hay không, một ô Dùng thử và một ví dụ cURL. Xuất bản điểm cuối không tự xuất bản tài liệu — bạn chọn khi nào muốn chia sẻ.

1. Xuất bản ít nhất một điểm cuối và lưu mọi thay đổi. Trước khi làm vậy, thanh Tài liệu API ở đầu Quản trị›API ghi Chưa xuất bản và cho biết còn thiếu gì.

2. Nhấp vào Xuất bản tài liệu.

   

3. Lúc này thanh ghi Đã xuất bản. Nhấp vào Sao chép liên kết tài liệu để chia sẻ địa chỉ, hoặc Mở tài liệu API bên dưới Khóa API để xem trang. Địa chỉ có dạng https://monstarx.com/api-docs/<your project id>.

monstarx.com

Trang mở đầu bằng tên và mô tả dự án, số điểm cuối được liệt kê, ID dự án và địa chỉ gốc. Ai có liên kết cũng đọc được, và công cụ tìm kiếm được yêu cầu không lập chỉ mục trang này. Trang chỉ hiện điểm cuối đang hoạt động và không bao giờ hiện khóa. Liên kết OpenAPI JSON ở đầu trang dẫn tới cùng nội dung mô tả đó dưới dạng tệp.

Để gỡ tài liệu, nhấp vào Hủy xuất bản tài liệu: trang và tệp OpenAPI ngừng hoạt động, còn các điểm cuối vẫn tiếp tục trả lời. Nếu bạn tạm ngừng mọi điểm cuối, tài liệu cũng bị hủy xuất bản, và bạn xuất bản lại khi sẵn sàng.

Yêu cầu và câu trả lời trông thế nào?

Mọi điểm cuối đều nằm dưới https://monstarx.com/api/rest/<your project id>, tiếp theo là đường dẫn của điểm cuối.

Liệt kê

curl 'https://monstarx.com/api/rest/<project id>/recipes?page=1&limit=25'

{
  "data": [
    { "id": "41a6…", "title": "Street tacos al pastor", "country_code": "MX" }
  ],
  "page": 1,
  "limit": 25,
  "hasMore": false
}

limit là từ 1 tới 100 bản ghi mỗi trang (mặc định 25 nếu bỏ trống) và page từ 1 tới 100. hasMore cho biết còn trang tiếp theo hay không.

Tạo

curl -X POST 'https://monstarx.com/api/rest/<project id>/recipes' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Lemon ricotta pancakes", "country_code": "IT"}'

Câu trả lời (mã trạng thái 201) chứa bản ghi mới trong data cùng id của bản ghi.

Cập nhật và xóa

curl -X PATCH 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Fluffy lemon ricotta pancakes"}'

curl -X DELETE 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY'

Cập nhật trả về bản ghi đã thay đổi; Xóa trả về { "deleted": true }.

Quy tắc cho dữ liệu bạn gửi:

• Một đối tượng JSON kèm Content-Type: application/json, tối đa 64 KB.
• Chỉ các trường cho phép truy cập, mỗi trường là một giá trị đơn giản: văn bản (tối đa 20.000 ký tự), số, true/false hoặc null.
• Không thể đặt hay đổi id, và cũng không thể đổi các trường chỉ đọc trong Quản trị.

Khi có lỗi, câu trả lời có thông báo error và mã trạng thái: 400 (yêu cầu không đúng), 401 (cần khóa API dự án hợp lệ), 403 (bảng hoặc thao tác đó không được phép trong Quản trị), 404 (không có điểm cuối hoặc bản ghi đó), 409 (xung đột, như bị trùng), 413 (câu trả lời sẽ vượt quá 1 MB — hãy cho phép truy cập ít trường hơn hoặc dùng trang nhỏ hơn).

Câu hỏi thường gặp

Vì sao tôi không nhấp được Xuất bản tài liệu?

Tài liệu cần ít nhất một điểm cuối đang hoạt động và không còn thay đổi chưa lưu. Đánh dấu Xuất bản điểm cuối ở một điểm cuối, nhấp vào Lưu và xuất bản điểm cuối, rồi nhấp Xuất bản tài liệu.

Tôi có cần xuất bản ứng dụng thì API mới hoạt động không?

Không. API đọc và ghi trực tiếp cơ sở dữ liệu của dự án, nên hoạt động ngay khi một điểm cuối được xuất bản. API dùng cùng dữ liệu với bản xem trước và ứng dụng đang hoạt động, và không cần xây dựng, không cần AI, không tốn điểm sử dụng.

Một trang web có gọi API của tôi từ trình duyệt được không?

Được, bất kỳ trang web nào cũng gọi được điểm cuối của bạn. Hãy dùng điểm cuối Đọc công khai từ trang web, và giữ các lệnh gọi cần khóa trên máy chủ để khóa luôn bí mật.

Tôi làm mất một khóa API. Có xem lại được không?

Không, mỗi khóa chỉ hiện một lần. Hãy tạo khóa mới, chuyển dịch vụ sang dùng khóa đó, rồi Thu hồi khóa cũ.

Vì sao tôi không xuất bản được một điểm cuối?

Với Tạo, Cập nhật hoặc Xóa, hãy bật thao tác đó cho bảng trong Quản trị trước. Ứng dụng có cơ sở dữ liệu đang hoạt động chạy trên tài khoản Cloudflare của riêng bạn thì không xuất bản được điểm cuối từ MonstarX, vì cơ sở dữ liệu ở đây chỉ chứa dữ liệu thử nghiệm của bản xem trước.

Tôi có nhận được webhook khi dữ liệu thay đổi không?

Không từ Quản trị → API, vì mục này chỉ trả lời yêu cầu. Hãy yêu cầu MonstarX thêm webhook vào ứng dụng — ví dụ “khi có đơn hàng mới, gửi POST tới địa chỉ này”.

Liên quan

Trang quản trị của ứng dụngNơi có API, cùng các bảng, người dùng và hoạt động của bạn.

Cơ sở dữ liệu của ứng dụngCác bảng mà điểm cuối đọc và ghi.

Giá trị bí mật và khóa APIKhóa ứng dụng dùng cho các dịch vụ khác.

Dùng MonstarX từ tác nhân lập trìnhĐiều khiển chính MonstarX từ Claude Code, Cursor và các công cụ khác.