Changelog API

Bộ đếm hạn mức hằng ngày được đặt lại vào đầu mỗi ngày UTC, không có ngoại lệ. Mọi phản hồi đều mang X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset, nên máy khách đã dùng hết hạn mức có thể lên lịch thử lại theo dấu thời gian đặt lại thay vì liên tục hỏi API.

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1786060800

Các điểm cuối có phiên bản nay gửi Access-Control-Expose-Headers, nhờ đó mã chạy trong trình duyệt có thể đọc X-API-Version, Deprecation, Sunset và Link. Những header này luôn có trong phản hồi nhưng trước đây JavaScript khác nguồn không nhìn thấy.

Access-Control-Expose-Headers: X-API-Version, Deprecation, Sunset, Link

Thay đổi trên bề mặt v1 chỉ mang tính bổ sung: các trường không bị xóa hay đổi tên, và thay đổi phá vỡ tương thích sẽ ra mắt dưới dạng đường dẫn phiên bản mới, được báo trước qua header Deprecation và Sunset. Vì trường mới có thể xuất hiện bất cứ lúc nào, máy khách nên bỏ qua các trường không nhận ra. X-API-Version chuyển sang 1.1.0 cùng cam kết này.

X-API-Version: 1.1.0

Các khóa riêng cho từng sản phẩm đã hợp nhất thành một khóa ak_ duy nhất. Khi tạo khóa, bạn chọn các phạm vi mà khóa được phép truy cập — tools, data, analytics, analyze, news và workflow — và lệnh gọi tới điểm cuối ngoài phạm vi đó sẽ bị từ chối. Khóa tạo trước thay đổi này vẫn giữ nguyên quyền truy cập cũ.

POST /api/v1/keys

{
  "name": "production",
  "scopes": ["tools", "data", "news"]
}

Tài khoản miễn phí có thể tạo một khóa API và thực hiện tối đa 50 yêu cầu mỗi ngày, với mức đỉnh 2 yêu cầu mỗi giây. Batch, chain, webhook, preset và xuất dữ liệu phân tích vẫn thuộc Akousa Pro.

Tất cả phản hồi v1 hiện bao gồm header X-API-Version: 1.0.0. Máy khách có thể sử dụng header này để xác minh phiên bản API nào phục vụ phản hồi và triển khai logic nhận biết phiên bản trong tích hợp của họ.

X-API-Version: 1.0.0

Các điểm cuối dưới /api/v1/data/* trả lời bằng một cấu trúc duy nhất: dữ liệu nằm trong data, thông tin phân phối nằm trong meta — dịch vụ nào đã trả lời, nguồn thượng nguồn, phản hồi có đến từ bộ nhớ đệm hay không và mất bao lâu. Cùng một đoạn mã phân tích dùng được cho mọi tập dữ liệu.

{
  "data": [ ... ],
  "meta": {
    "service": "earthquakes",
    "source": "usgs",
    "cached": true,
    "executionMs": 34
  }
}

API được phiên bản qua đường dẫn URL. Phiên bản hiện tại là v1. Thay đổi đột phá sẽ tạo phiên bản mới.

Deprecation: @1772323200
Link: </docs/api/changelog#changelog-deprecationHeaders>; rel="deprecation", </api/v1/tools/{slug}>; rel="successor-version"

API sử dụng mã trạng thái HTTP chuẩn. Phản hồi lỗi bao gồm nội dung JSON với trường error mô tả vấn đề.

{
  "ok": false,
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "status": 401
}

Xác thực bằng một khóa API duy nhất, gửi yêu cầu HTTP tiêu chuẩn và nhận về các phản hồi JSON có thể dự đoán được. Đặc tả OpenAPI 3.1 đầy đủ cùng các ví dụ mã tương tác bằng 8 ngôn ngữ giúp việc tích hợp diễn ra nhanh chóng.