Skip to content

Phiên bản API ​

AstroAPI đánh phiên bản cho các thay đổi phá vỡ tương thích bằng một ngày tương thích thay vì một số phiên bản trong URL. Đường dẫn của các điểm cuối không bao giờ thay đổi; bạn ghim một ngày và tiếp tục nhận đúng hành vi đang có hiệu lực vào ngày đó.

Phiên bản của bạn ​

Gửi ngày tương thích mà bạn đã xây dựng dựa trên đó trong header X-Api-Version:

http
GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01

Một phản hồi được định hình bởi một ngày tương thích sẽ cho bạn biết đó là ngày nào:

http
X-Api-Version: 2026-01-01
Vary: X-Api-Version

Những điểm cuối có đầu ra không phụ thuộc phiên bản sẽ bỏ cả hai header. GET /api/modules trả về cùng một nội dung vào mọi ngày, nên không có gì để báo và cũng không có gì để bộ nhớ đệm phải phân tách. Nếu bạn gửi X-Api-Version một cách tường minh, nó sẽ được phản hồi lại ở bất kỳ điểm cuối nào, nhờ đó bạn luôn xác nhận được rằng một giá trị đã được chấp nhận.

Để đọc lại phiên bản mà tổ chức của bạn phân giải tới, hãy dùng GET /api/org/api-version; effectiveApiVersion của nó là ngày được áp dụng khi một yêu cầu không mang header riêng.

Nếu bạn không gửi header, các yêu cầu sẽ dùng phiên bản đã ghim của tổ chức, và nếu bạn chưa ghim phiên bản nào thì dùng mốc cơ sở 2026-01-01. Hành vi mới không bao giờ được áp dụng tự động cho bạn — một tích hợp viết hôm nay vẫn tiếp tục chạy y nguyên, bất kể sau này chúng tôi phát hành gì.

Nhật ký thay đổi ​

Mỗi thay đổi phá vỡ tương thích được liệt kê ở đây kèm ngày có hiệu lực. Ghim một ngày sẽ cho bạn mọi thay đổi vào ngày đó hoặc trước đó.

NgàyThay đổi
2026-09-03aspects trên POST /api/calc/transit được nhóm lại: mỗi hành tinh vận hành, góc chiếu và hành tinh gốc là một mục, với văn bản luận giải chỉ một lần và mỗi lần đi qua trong giai đoạn nằm dưới occurrences. Trước đây là một mục cho mỗi lần đi qua, mỗi mục lặp lại cùng văn bản. Xem Vận hành.
2026-09-10Mọi điểm trên POST /api/calc/natal mang declination (độ, bắc là dương) và outOfBounds (vượt quá xích vĩ cực đại của Mặt Trời cho ngày đó). Trước đây không có trường nào trong hai trường này. Xem Xích vĩ.

Mốc cơ sở 2026-01-01 là phiên bản cũ nhất chúng tôi phục vụ. Ghim một ngày sớm hơn vẫn được chấp nhận và sẽ phân giải về mốc cơ sở.

Ghim tổ chức của bạn ​

Thay vì thêm một header vào mỗi lệnh gọi, hãy ghim tổ chức của bạn một lần. Khi đó mọi yêu cầu không chỉ định phiên bản sẽ dùng ngày ấy.

bash
curl -X PATCH "https://api.astroapi.cloud/api/org/api-version" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key" \
  -d '{
    "data": {
      "type": "organizations",
      "attributes": { "apiVersion": "2026-01-01" }
    }
  }'

Đọc lại giá trị đã ghim hiện tại, cùng với phạm vi bạn có thể chọn:

bash
curl "https://api.astroapi.cloud/api/org/api-version" \
  -H "X-Api-Key: your_api_key"
json
{
  "data": {
    "type": "organizations",
    "id": "org_123",
    "attributes": {
      "apiVersion": "2026-01-01",
      "effectiveApiVersion": "2026-01-01",
      "baselineApiVersion": "2026-01-01",
      "latestApiVersion": "2026-01-01"
    }
  }
}

Gửi "apiVersion": null để xoá giá trị đã ghim và quay về mốc cơ sở.

Nâng cấp an toàn ​

Header luôn thắng giá trị ghim của tổ chức, điều này cho phép triển khai một cách an toàn:

  1. Đọc nhật ký thay đổi ở trên và kiểm tra những thay đổi nào nằm giữa ngày hiện tại của bạn và ngày mới.
  2. Gửi ngày mới trong X-Api-Version trên một vài yêu cầu, hoặc trong môi trường staging của bạn, và kiểm chứng các phản hồi.
  3. Khi đã hài lòng, hãy ghim tổ chức vào ngày mới và bỏ header đi.

Vì header ghi đè giá trị ghim theo từng yêu cầu, bạn cũng có thể làm ngược lại: ghim tổ chức tiến lên phía trước và tạm thời gửi một ngày cũ hơn từ một dịch vụ mà bạn chưa chuyển đổi.

Client trình duyệt và nhúng ​

Những ngữ cảnh không thể đặt header yêu cầu — nhúng <img>, <iframe> và <script>, các URL biểu đồ đã ký — chấp nhận ngày dưới dạng tham số truy vấn:

https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...

Header được ưu tiên khi cả hai cùng có mặt. Với fetch() và XHR, hãy dùng header; X-Api-Version được CORS cho phép và được phơi bày trên phản hồi, nên bạn có thể đọc lại phiên bản nào đã được áp dụng.

Xác thực ​

Một giá trị sai định dạng trả về 400 Bad Request thay vì âm thầm lùi về mặc định:

json
{
  "error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}

Giá trị phải là một ngày lịch có thật ở dạng YYYY-MM-DD. Một ngày đúng định dạng nhưng nằm ngoài phạm vi được hỗ trợ sẽ bị kẹp lại chứ không bị từ chối: sớm hơn mốc cơ sở sẽ phân giải về mốc cơ sở, muộn hơn thay đổi mới nhất sẽ phân giải về hành vi mới nhất.

Bộ nhớ đệm ​

Những phản hồi có nội dung khác nhau theo phiên bản được đánh dấu Vary: X-Api-Version, nhờ đó một bộ nhớ đệm dùng chung hay CDN đặt trước tích hợp của bạn sẽ tách riêng các phiên bản ấy. Những phản hồi giống nhau vào mọi ngày không mang Vary, cho phép bộ nhớ đệm phục vụ một mục duy nhất cho tất cả bên gọi thay vì một mục cho mỗi ngày. Nếu bạn tự lưu đệm phản hồi API, hãy đưa ngày tương thích vào khoá đệm cho những điểm cuối có mang header này.

Điều gì được tính là thay đổi phá vỡ tương thích ​

Những thay đổi được cấp một ngày và xuất hiện trong nhật ký:

  • Xoá hoặc đổi tên một trường trong phản hồi
  • Thay đổi kiểu hoặc hình dạng của một trường hiện có
  • Biến một trường tuỳ chọn thành bắt buộc, hoặc một trường có thể vắng mặt thành luôn có mặt
  • Thay đổi ý nghĩa của một giá trị hiện có
  • Gỡ bỏ một điểm cuối hoặc thay đổi ngữ nghĩa của nó

Những thay đổi phát hành không kèm phiên bản, vì chúng không thể làm hỏng một client đúng đắn:

  • Thêm một điểm cuối mới
  • Thêm một tham số yêu cầu tuỳ chọn mới
  • Thêm một trường mới vào phản hồi
  • Thêm một giá trị mới vào một enum mà bạn chỉ đọc
  • Sửa lỗi để đưa hành vi khớp với tài liệu

Hãy viết tích hợp của bạn sao cho bỏ qua các trường phản hồi lạ. Những thay đổi mang tính bổ sung sẽ đến với mọi phiên bản, kể cả phiên bản của bạn.

AstroAPI Documentation