Bài 24 — Confluence REST API — JIRA and Confluence for BA

Mở đầu — vì sao bài này quan trọng

Hãy tưởng tượng bạn là BA tại một công ty fintech ở TP.HCM. Sếp nhắn: "Em tạo giúp 80 trang Confluence cho 80 màn hình của app mobile, mỗi trang theo đúng template chuẩn, xong trong sáng nay." Nếu làm thủ công, bạn sẽ click "Create page" 80 lần, copy-paste template 80 lần, đổi tiêu đề 80 lần — mất nguyên ngày và chắc chắn sai sót. Nhưng nếu bạn biết gọi Confluence REST API, cùng một việc đó chỉ là một vòng lặp chạy trong 30 giây.

REST API (Representational State Transfer Application Programming Interface) là "cánh cửa lập trình" để bạn nói chuyện với Confluence bằng code thay vì bằng chuột. Mọi thứ bạn làm trên giao diện web — tạo trang, sửa nội dung, tìm kiếm, gắn nhãn, xuất dữ liệu — đều có một endpoint API tương ứng.

Tại sao một BA, vốn không phải developer, lại cần học cái này? Vì ranh giới giữa BA và "BA biết tự động hóa" đang ngày càng quyết định giá trị của bạn. Một BA biết API có thể: di chuyển hàng trăm tài liệu giữa các hệ thống mà không cần xin IT; đồng bộ knowledge base với hệ thống nội bộ; xuất toàn bộ tài liệu nghiệp vụ ra để audit; và quan trọng nhất — thoát khỏi những công việc lặp đi lặp lại nhàm chán. Bài này không yêu cầu bạn trở thành lập trình viên, chỉ cần hiểu cơ chế và biết đọc một đoạn lệnh mẫu.

Lưu ý quan trọng về phạm vi: bài này tập trung vào Confluence REST API (làm việc với spaces, pages, content). API của JIRA là một chủ đề riêng đã có bài khác phụ trách, nên ở đây ta chỉ nói về Confluence.

Khái niệm cốt lõi

REST API hoạt động như thế nào

Mỗi lần gọi API là một "yêu cầu" (request) gửi tới một địa chỉ URL (gọi là endpoint), và Confluence trả về một "phản hồi" (response) thường ở định dạng JSON — một dạng văn bản có cấu trúc mà cả người lẫn máy đọc được.

Có bốn loại hành động (HTTP method) bạn cần nhớ:

GET — lấy dữ liệu (đọc một trang, tìm kiếm). Không thay đổi gì.
POST — tạo mới (tạo trang mới).
PUT — cập nhật (sửa nội dung trang đã có).
DELETE — xóa.

Một cách dễ nhớ: GET là "cho tôi xem", POST là "tạo cho tôi", PUT là "sửa giúp tôi", DELETE là "bỏ đi".

Hai phiên bản API: v1 và v2

Confluence Cloud hiện có hai thế hệ API. Bạn cần phân biệt vì tài liệu trên mạng hay lẫn lộn:

API v1 (REST API cũ): endpoint dạng /wiki/rest/api/content. Vẫn dùng được, nhiều ví dụ cũ trên mạng theo phiên bản này.
API v2 (REST API mới): endpoint dạng /wiki/api/v2/pages. Atlassian khuyến khích dùng v2 cho dự án mới vì nhanh hơn và rõ ràng hơn.

Trong bài này tôi sẽ dùng v2 cho các ví dụ chính, nhưng nguyên lý hoàn toàn giống nhau.

Xác thực (Authentication)

Confluence không cho người lạ gọi API. Bạn phải chứng minh "tôi là ai". Với Confluence Cloud, cách phổ biến nhất cho BA là dùng API Token:

Vào id.atlassian.com → Security → Create and manage API tokens.
Tạo token mới, copy lại (chỉ hiện một lần).
Khi gọi API, bạn gửi kèm email và token này theo cơ chế Basic Auth.

Token giống như mật khẩu — tuyệt đối không dán vào chat nhóm, không commit lên Git. Nếu lộ, vào trang đó thu hồi (revoke) ngay.

Khái niệm "storage format"

Đây là điểm khiến nhiều BA vấp ngã. Nội dung trang Confluence khi gửi qua API không phải là chữ bạn gõ bình thường, mà là một dạng HTML đặc biệt gọi là storage format. Ví dụ, một panel thông tin (info macro) trong storage format trông như thế này:

<ac:structured-macro ac:name="info">
  <ac:rich-text-body><p>Nội dung lưu ý</p></ac:rich-text-body>
</ac:structured-macro>

Hiểu nôm na: khi tạo trang qua API, bạn phải "nói chuyện" bằng ngôn ngữ storage format chứ không phải gõ chữ thường. Mẹo thực dụng: tạo một trang mẫu thủ công trên web, rồi gọi GET để xem chính xác storage format của nó, sau đó copy làm khuôn.

Các use case chính cho BA

Mass create pages from template: tạo hàng loạt trang theo một khuôn mẫu — ví dụ 80 trang đặc tả màn hình.
Export Confluence to other systems: kéo toàn bộ tài liệu ra để đưa vào hệ thống audit, data warehouse, hoặc backup.
Sync with external knowledge bases: đồng bộ nội dung giữa Confluence và một hệ thống tri thức khác (ví dụ portal nội bộ).
Custom reporting & automation: tự động đếm trang chưa cập nhật, liệt kê trang thiếu nhãn, gửi cảnh báo.

Tình huống thực tế

Ví dụ 1 — Tạo hàng loạt trang đặc tả màn hình tại một startup logistics

Công ty giao hàng GiaoNhanh (giả định, trụ sở Hà Nội) đang xây app tài xế với 64 màn hình. BA tên Linh cần tạo 64 trang Confluence, mỗi trang theo template "Screen Spec" gồm các mục: Mô tả, Wireframe, Business rules, Acceptance criteria.

Làm thủ công, Linh ước tính mất khoảng 3 phút/trang để tạo, đặt tên, dán template — tức gần 3,5 giờ và rất dễ đặt tên lệch chuẩn. Thay vào đó, chị chuẩn bị một file danh sách 64 tên màn hình, viết một đoạn script gọi POST /wiki/api/v2/pages trong vòng lặp. Mỗi vòng lặp gửi: spaceId của space dự án, tiêu đề (ví dụ "SCR-012 — Màn hình xác nhận giao hàng"), và body là storage format của template với tiêu đề được chèn động.

Kết quả: 64 trang được tạo trong chưa đầy một phút, tên hoàn toàn nhất quán, đúng template. Linh dành thời gian còn lại để thực sự viết nội dung nghiệp vụ thay vì click chuột.

Bài học: API không thay bạn viết nghiệp vụ, nhưng nó xóa bỏ phần "lao động chân tay" của việc tạo cấu trúc. Khi số lượng trang vượt khoảng 15–20, hãy nghĩ đến API.

Ví dụ 2 — Xuất tài liệu phục vụ kiểm toán tại một ngân hàng

Một ngân hàng tầm trung ở TP.HCM bị yêu cầu cung cấp toàn bộ tài liệu BRD và đặc tả của một dự án core-banking cho đợt kiểm toán nội bộ, dưới dạng file lưu trữ ngoài Confluence. Có khoảng 230 trang trong space.

BA phụ trách dùng GET /wiki/api/v2/spaces/{id}/pages để lấy danh sách tất cả trang (có phân trang — pagination — vì API chỉ trả về tối đa 25–250 trang mỗi lần gọi). Với mỗi page ID, anh gọi tiếp GET /wiki/api/v2/pages/{id}?body-format=storage để lấy nội dung, rồi lưu thành file. Anh cũng lấy kèm metadata: ngày tạo, ngày sửa cuối, tác giả — đúng những thông tin kiểm toán viên cần.

Toàn bộ 230 trang được xuất sạch sẽ trong vài phút, kèm một bảng tổng hợp ngày cập nhật. Nếu làm tay, đây là công việc cả tuần với rủi ro bỏ sót trang.

Bài học: Khi cần "lôi" dữ liệu ra khỏi Confluence với số lượng lớn — audit, migration, backup — API là con đường duy nhất hợp lý. Đừng quên xử lý pagination: API trả về theo từng "trang kết quả", bạn phải lặp cho đến khi hết.

Ví dụ 3 — Đồng bộ FAQ sang knowledge base nội bộ tại một công ty SaaS

Công ty SaaS VietDesk (giả định, Đà Nẵng) viết tài liệu hỗ trợ khách hàng trong Confluence, nhưng khách hàng đọc trên một portal riêng. Trước đây, mỗi lần sửa FAQ trong Confluence, team support phải copy thủ công sang portal — thường trễ vài ngày, gây sai lệch thông tin.

BA xây một quy trình tự động: mỗi đêm, một script gọi API tìm các trang có nhãn (label) "public-faq" được sửa trong 24 giờ qua, dùng truy vấn CQL (Confluence Query Language) qua endpoint /wiki/rest/api/content/search?cql=label="public-faq" and lastmodified >= now("-1d"). Với mỗi trang thay đổi, script lấy nội dung và đẩy sang API của portal.

Sau khi áp dụng, độ trễ đồng bộ giảm từ vài ngày xuống dưới 24 giờ, và team support không còn phải copy tay.

Bài học: API biến Confluence từ một "ốc đảo tài liệu" thành một mắt xích trong hệ sinh thái dữ liệu của công ty. CQL là công cụ lọc cực mạnh giúp bạn chỉ xử lý đúng phần cần thiết thay vì quét toàn bộ.

Hướng dẫn từng bước

Ta sẽ đi qua một quy trình hoàn chỉnh: tạo một trang mới qua API. Tôi dùng curl (công cụ dòng lệnh phổ biến, có sẵn trên macOS/Linux) cho dễ minh họa; bạn có thể làm điều tương tự bằng Postman nếu ngại dòng lệnh.

Bước 1 — Lấy API Token. Vào id.atlassian.com → Security → API tokens → Create. Copy token và lưu nơi an toàn.

Bước 2 — Xác định spaceId. Bạn cần ID của space muốn tạo trang. Gọi:

curl -u 'email@cty.com:API_TOKEN' \
  'https://yourcompany.atlassian.net/wiki/api/v2/spaces?keys=BA'

Confluence trả về JSON chứa id của space có key "BA". Ghi lại số đó.

Bước 3 — Thử nghiệm với một request GET trước. Luôn đọc trước khi ghi. Lấy thử một trang đã có để chắc chắn xác thực hoạt động:

curl -u 'email@cty.com:API_TOKEN' \
  'https://yourcompany.atlassian.net/wiki/api/v2/pages/123456?body-format=storage'

Nếu thấy JSON nội dung trang, bạn đã kết nối thành công và biết storage format trông ra sao.

Bước 4 — Tạo trang mới bằng POST. Gửi một request POST với body JSON:

curl -u 'email@cty.com:API_TOKEN' \
  -X POST \
  -H 'Content-Type: application/json' \
  'https://yourcompany.atlassian.net/wiki/api/v2/pages' \
  -d '{
    "spaceId": "98765",
    "status": "current",
    "title": "BRD - Module thanh toan",
    "body": {
      "representation": "storage",
      "value": "<p>Noi dung mo dau</p>"
    }
  }'

Nếu thành công, Confluence trả về mã 200/201 kèm JSON chứa ID của trang vừa tạo.

Bước 5 — Tự động hóa thành vòng lặp. Khi cần tạo nhiều trang, bạn đưa bước 4 vào một vòng lặp đọc danh sách tiêu đề từ file. Đây chính là kỹ thuật "mass create" mà Linh dùng ở Ví dụ 1.

Bước 6 — Cập nhật trang (PUT). Khi sửa trang đã có, lưu ý Confluence dùng cơ chế version: bạn phải gửi kèm số version mới (version cũ + 1), nếu không sẽ bị từ chối. Quy trình: GET để lấy version hiện tại → PUT với version+1.

Lỗi thường gặp & mẹo

Quên tăng version khi PUT: Lỗi kinh điển. Cập nhật trang yêu cầu version.number mới = số cũ + 1. Nếu gửi sai, bạn nhận lỗi 409 (Conflict). Luôn GET version hiện tại trước khi PUT.

Gửi nội dung sai định dạng: Dán chữ thường vào field body sẽ ra trang lỗi hoặc mất định dạng. Nhớ rằng body phải là storage format, và representation phải đúng là "storage".

Quên xử lý pagination: Khi GET danh sách, đừng tưởng kết quả đầu tiên là tất cả. API trả về theo lô, kèm một link _links.next. Phải lặp theo link đó cho đến khi hết, nếu không bạn sẽ "bỏ sót" hàng trăm trang mà không biết.

Rate limiting (giới hạn tần suất): Confluence Cloud giới hạn số request/phút. Nếu chạy vòng lặp quá nhanh trên ngàn trang, bạn sẽ bị trả về lỗi 429 (Too Many Requests). Mẹo: thêm độ trễ nhỏ giữa các request, và nếu gặp 429 thì đợi theo giá trị trong header Retry-After.

Lỗi 401/403: 401 là sai xác thực (kiểm tra lại email và token, đảm bảo dùng email Atlassian chứ không phải username). 403 là đúng người nhưng không đủ quyền — bạn cần quyền tạo/sửa trên space đó.

Mẹo dùng Postman trước khi viết script: Nếu bạn không quen code, hãy thử mọi request trong Postman trước. Postman có giao diện trực quan, lưu lịch sử request, và còn xuất ra đoạn code mẫu cho bạn. Đây là cây cầu lý tưởng cho BA mới làm quen API.

Mẹo lấy storage format chuẩn: Đừng tự gõ macro phức tạp bằng tay. Tạo trang mẫu trên web với đầy đủ macro bạn muốn, rồi GET nó ra để copy storage format. Nhanh và không sai cú pháp.

Luôn test trên space nháp: Trước khi chạy script tạo/xóa hàng loạt trên space thật, hãy thử trên một space "sandbox". Một vòng lặp DELETE sai có thể xóa nhầm 200 trang trong vài giây.

Bài tập thực hành

Tạo token và kết nối: Tạo một API token cá nhân. Dùng curl hoặc Postman gọi GET để lấy danh sách spaces bạn có quyền truy cập. Mục tiêu: thấy được JSON trả về và xác định spaceId của một space test.

Đọc storage format: Tạo thủ công một trang có chứa một Info panel và một bảng. Sau đó GET trang đó với body-format=storage. Quan sát cấu trúc ac:structured-macro — ghi lại để sau này tái sử dụng.

Tạo một trang qua API: Dùng POST tạo một trang mới trong space test với tiêu đề "Test API - [tên bạn]" và một đoạn nội dung đơn giản. Kiểm tra trên web xem trang đã xuất hiện chưa.

Mass create (nâng cao): Viết một vòng lặp (bằng curl trong shell, hoặc Python với thư viện requests) tạo 5 trang con theo cùng một template, tên lần lượt "SCR-01" đến "SCR-05". Đây là mô phỏng thu nhỏ của Ví dụ 1.

Xuất dữ liệu (nâng cao): GET danh sách tất cả trang trong space test, có xử lý pagination, và in ra tiêu đề + ngày sửa cuối của từng trang. Đây là nền tảng cho use case audit/export.

Tóm tắt

Confluence REST API là công cụ giúp BA thoát khỏi những công việc tài liệu lặp đi lặp lại và mở khóa các khả năng mà giao diện web không làm nổi: tạo hàng loạt trang, xuất dữ liệu phục vụ audit, đồng bộ với hệ thống ngoài, và tự động hóa báo cáo.

Những điểm cốt lõi cần nhớ: bốn HTTP method (GET/POST/PUT/DELETE) tương ứng với đọc/tạo/sửa/xóa; xác thực bằng API Token theo Basic Auth; nội dung trang dùng storage format chứ không phải chữ thường; cập nhật trang phải tăng version; và luôn xử lý pagination cùng rate limiting khi làm việc số lượng lớn. CQL là công cụ lọc mạnh khi bạn chỉ muốn xử lý đúng phần cần thiết.

Bạn không cần trở thành lập trình viên. Chỉ cần hiểu cơ chế, biết đọc một request mẫu, và dùng Postman làm bàn đạp — bạn đã có thể tự xử lý những việc mà trước đây phải đi nhờ IT. Đó chính là khác biệt giữa một BA bình thường và một BA biết tự động hóa.