Quản lý phiên bản

AstroWay API dùng URL versioning: phiên bản nằm ngay trong đường dẫn của request. Cách này đơn giản hơn so với phiên bản qua header và được các proxy cache tốt.

https://api.astroway.info/v1/chart

SemVer cho API

Chúng tôi tuân theo quy ước của semver.org:

• MAJOR (v1 → v2): thay đổi không tương thích ngược. Phiên bản cũ vẫn hoạt động ít nhất 12 tháng sau khi phát hành phiên bản mới.
• MINOR: endpoint mới, trường tùy chọn mới. Luôn tương thích ngược.
• PATCH: sửa lỗi, tinh chỉnh độ chính xác. Hiển thị qua header X-Api-Version: 1.12.3 trong response.

Những gì không được coi là breaking change

• Thêm endpoint mới
• Thêm trường tùy chọn mới vào request body
• Thêm trường mới vào response
• Chỉnh sửa nội dung thông báo lỗi (giá trị code vẫn giữ nguyên)
• Thay đổi độ chính xác tính toán trong phạm vi đã công bố ±1” (hành tinh) / ±1’ (nhà)
• Tăng rate limit hoặc credit budget trong gói của bạn

Điều này có nghĩa là code của bạn không được lỗi khi response có thêm trường mới. Chỉ parse những gì bạn cần, bỏ qua phần còn lại.

Những gì là breaking change (chỉ trong bản phát hành major)

• Xóa hoặc đổi tên endpoint
• Xóa hoặc đổi tên trường trong response
• Thay đổi kiểu của trường (ví dụ, number → string)
• Thay đổi ngữ nghĩa của trường (cùng một tên nhưng mang ý nghĩa khác)
• Thay đổi code trong response lỗi
• Siết chặt validation theo cách có thể làm hỏng các request trước đây vẫn hợp lệ

Changelog

Mọi thay đổi đều có trong Changelog. Bản phát hành minor ra mỗi 2–4 tuần, bản patch ra khi sẵn sàng.

Đăng ký nhận cập nhật:

• RSS: https://api.astroway.info/changelog/rss.xml
• Email: Settings → Notifications → Product updates trong dashboard

Chính sách deprecation

Khi một trường hoặc endpoint bị deprecated:

1. Chúng tôi thông báo trong changelog kèm email
2. Response xuất hiện header Deprecation: Sun, 01 Nov 2026 00:00:00 GMT (theo chuẩn RFC 8594)
3. API bị deprecated vẫn hoạt động ít nhất 12 tháng
4. Việc xóa: chỉ trong bản phát hành major tiếp theo