Tham chiếu
Phiên bản và độ ổn định
Các loại số phiên bản của O3O Office Online, cam kết ổn định của API v1, thay đổi nào là tương thích và mức ổn định của từng phần.
Trong trang này
O3O Office Online dùng nhiều loại số phiên bản cho những thứ đổi theo nhịp khác nhau. Điều bên tích hợp cần bám là phiên bản hợp đồng API; phiên bản dịch vụ chỉ để biết đang chạy bản nào.
Các loại số phiên bản#
| Loại | Hiện tại | Đọc ở đâu | Đổi khi |
|---|---|---|---|
| Hợp đồng API | v1 | Tiền tố /v1/; trường api của /o3o/status và /v1/status | Chỉ khi có thay đổi phá vỡ. |
| Phiên bản dịch vụ | 1.0.0 | Trường version của /o3o/status và /v1/status | Mỗi lần phát hành, dạng MAJOR.MINOR.PATCH. |
| Lõi xử lý tài liệu | theo image | core của /v1/status; upstream.coolwsd_version của /o3o/status | Khi đổi image. |
| o3oscript | 1 | Trường o3oscript ở gốc kịch bản | Chỉ khi lược đồ kịch bản phá vỡ. |
| Định dạng token bản quyền | v = 1 hoặc 2 | Trường v trong payload | Khi định dạng token đổi. |
Tệp kê khai versions.json | Gốc repo | Mỗi lần phát hành; là nguồn của Ma trận tương thích. |
# Phiên bản gate, DocBuilder và lõi xử lý tài liệu
curl -s http://localhost:8080/o3o/status | jq '{service, version, api, upstream}'
curl -s http://localhost:8080/v1/status | jq '{service, version, api, core}'Cam kết ổn định của API v1#
Trong suốt v1, O3O chỉ thay đổi API theo cách tương thích ngược. Mọi thay đổi phá vỡ chờ tới phiên bản API mới.
| Thay đổi tương thích (vẫn là v1) | Thay đổi phá vỡ (cần v2) |
|---|---|
| Thêm endpoint mới | Xoá hoặc đổi tên endpoint |
| Thêm trường TUỲ CHỌN vào yêu cầu | Thêm trường BẮT BUỘC vào yêu cầu |
| Thêm trường vào phản hồi, callback hay sự kiện | Xoá, đổi tên hoặc đổi kiểu một trường |
| Thêm mã lỗi mới, loại sự kiện callback mới, giá trị liệt kê mới | Đổi mã HTTP hay code của một trường hợp đã có |
Đổi câu chữ của message | Đổi định dạng lỗi thống nhất |
| Thêm định dạng vào ma trận chuyển đổi | Đổi thuật toán ký (HS256, HMAC SHA-256, Ed25519) hoặc cách tính chữ ký |
Viết mã tích hợp để luôn tương thích#
- Bỏ qua trường lạ trong phản hồi, callback và token.
- Xử lý
codelỗi lạ theo nhóm mã HTTP. - Trả 2xx cho loại sự kiện callback lạ thay vì báo lỗi.
- Không phân tích
message; không dựa vào thứ tự khoá JSON. - Kiểm trường
apibằngv1khi khởi động ứng dụng.
Khi có API v2#
API v2 sẽ mở ở tiền tố mới và chạy song song với v1 trong một thời gian. Thời hạn hỗ trợ v1 và ngày ngừng sẽ được công bố cùng lúc với v2 trên trang Nhật ký thay đổi.
Mức ổn định của từng phần#
| Phần | Mức |
|---|---|
DocBuilder /v1/* (11 endpoint), định dạng lỗi, header giới hạn tần suất | Ổn định |
/o3o/status, /o3o/limits, /o3o/healthz | Ổn định |
O3O.Editor: config, 7 sự kiện, 5 phương thức | Ổn định |
| Callback lưu tài liệu và callback job, cách ký | Ổn định |
| Định dạng token bản quyền, o3oscript v1 | Ổn định |
/o3o/demo* | Chỉ cho máy DEV; có thể đổi bất kỳ lúc nào |
/o3o/auth, /o3o/wopi/* | Nội bộ, không phải API công khai |
/browser, /cool, /hosting, /lool | Đường dẫn của máy chủ soạn thảo. Dùng qua O3O.Editor hoặc giao thức WOPI; chi tiết nội bộ có thể đổi theo image. |
| Con số hạn mức và giá | Theo plans.json; có thể đổi theo chính sách giá, không coi là thay đổi API |
Nhãn trạng thái trên trang tài liệu#
| Nhãn | Nghĩa |
|---|---|
| Ổn định | Có trong v1 và chịu cam kết ở trên. |
| Beta | Chạy được nhưng cách triển khai hoặc tài liệu còn có thể đổi, ví dụ bản Docker đang dùng image DEV. |
| Sắp có | Chưa cài đặt trong v1. Không dựa vào để lập kế hoạch cho tới khi chuyển sang ổn định. |