Bản đồ danh mục: cách cấu trúc 700+ endpoint AstroWay

Danh mục AstroWay hiện có 758 endpoint trong 57 nhóm. Với quy mô như vậy, câu hỏi chính của nhà tích hợp không phải là “liệu có đủ phạm vi phủ sóng không”, mà là “làm thế nào để không bị lạc”. Bài viết này là một bản đồ: cách danh mục được chia thành các miền và cách tìm thấy thứ bạn cần trong một phút.

Bất kể miền nào, mỗi endpoint tính toán đều có cùng một dạng:

POST /v1/{domain}/{calc}
X-Api-Key: aw_live_...
Content-Type: application/json

Phần thân là JSON với dữ liệu ngày sinh (ngày, giờ, tọa độ) hoặc các tham số kỹ thuật cụ thể. Phản hồi luôn là { "ok": true, "data": {...} } hoặc { "ok": false, "error": {...} }. Không có GraphQL, không có luồng xác thực riêng biệt cho từng miền: một khóa trong tiêu đề X-Api-Key, một định dạng phản hồi.

Điều này có nghĩa là lớp bao bọc mà bạn viết cho biểu đồ sinh phù hợp cho cả BaZi và runes - chỉ có đường dẫn và schema của phần thân thay đổi.

Danh mục được nhóm thành các miền lớn. Đây là bản đồ với các bộ đếm thực tế (các số được lấy từ manifest trong mỗi bản dựng, vì vậy chúng luôn được cập nhật tại đây):

Phần còn lại là các giải thích AI, tử vi, các endpoint tham chiếu (cung hoàng đạo, hành tinh, khía cạnh) và các endpoint hệ thống (health, usage, openapi).

174 endpoint Vệ Đà - nhiều hơn toàn bộ phần phương Tây. Lý do rất đơn giản: truyền thống Vệ Đà được hình thức hóa hơn. Trong khi chiêm tinh học phương Tây có một bộ nhà, chiêm tinh học Vệ Đà có 16 biểu đồ phân chia (varga), một số hệ thống dasha, hàng chục yogas với các quy tắc rõ ràng. Mỗi cái trong số này là một endpoint riêng biệt với kết quả xác định.

Nếu bạn xây dựng cho thị trường Ấn Độ, đây là cốt lõi của sản phẩm, chứ không phải là một tiện ích bổ sung.

Bất kể sự độc đáo của kỹ thuật, vị trí hành tinh được tính toán bởi một nhân duy nhất trên Swiss Ephemeris (WASM). Cùng một nhân đó hoạt động trong trình duyệt của ứng dụng của chúng tôi và trên máy chủ API - một cơ sở mã, không có sự khác biệt nào. Các endpoint tính toán được bao phủ bởi 873 bài kiểm tra snapshot, được đối chiếu với các nguồn tham chiếu trong mỗi PR. Chi tiết hơn về điều này - trong một bài viết riêng về độ chính xác của CI.

Ba cách, từ nhanh nhất:

1. Tài liệu OpenAPI - /docs/api/ được tạo trực tiếp từ đặc tả sản phẩm openapi.json. Các nhóm trong thanh bên = các miền ở trên. Mỗi endpoint có schema của phần thân, ví dụ và nút “thử”.
2. Danh mục MCP - nếu bạn đang sử dụng Claude hoặc Cursor, toàn bộ danh mục có sẵn dưới dạng một bộ công cụ thông qua mcp.astroway.info. Agent tự tìm endpoint cần thiết theo mô tả.
3. Tìm kiếm theo đặc tả - curl https://api.astroway.info/v1/openapi.json trả về một hợp đồng hoàn chỉnh có thể đọc được bằng máy. Thuận tiện cho việc tạo mã client của riêng bạn.

Khóa trên dashboard/sign-up cung cấp 10.000 tín dụng mỗi tháng - đủ để bạn khám phá hàng chục miền và hiểu cái nào là của bạn. Bạn không cần phải nghiên cứu toàn bộ danh mục: hãy chọn miền của bạn, phần còn lại sẽ chờ khi bạn cần.