Ba SDK chính thức: TypeScript, Python, PHP thay vì curl thô

Sử dụng curl hay fetch thô để gọi API thì được - hợp đồng đơn giản, chỉ một header X-Api-Key, JSON đi và về. Nhưng khi có hơn 758 endpoints và các request body có hàng chục trường, một client được type hóa sẽ tiết kiệm hàng giờ: tự động hoàn thiện đường dẫn, kiểu dữ liệu request và response, tự động retry trên mạng không ổn định.

Vì vậy chúng tôi có ba SDK chính thức, được tạo ra từ một hợp đồng OpenAPI 3.1 duy nhất.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

Cùng một lệnh gọi birth chart bằng ba ngôn ngữ khác nhau.

TypeScript - một wrapper nhẹ trên openapi-fetch (~6KB runtime), với tự động hoàn thiện đường dẫn:

import { Astroway } from '@astroway/sdk';

const aw = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const { data: chart } = await aw.client.POST('/chart', {
  body: {
    date: '1990-07-14',
    time: '14:30:00',
    timezoneOffset: 3,
    latitude: 50.4501,
    longitude: 30.5234,
    houseSystem: 'P',
  },
});

// aw.client.POST is the raw typed fetch, so `chart` is the { ok, data } envelope
console.log(chart.data.houses.ascendant);  // 212.0952574979425

Python - Astroway đồng bộ và AsyncAstroway không đồng bộ với cùng giao diện, trên httpx:

from astroway import Astroway

aw = Astroway(api_key=os.environ['ASTROWAY_API_KEY'])

chart = aw.post('/chart', body={
    'date': '1990-07-14',
    'time': '14:30:00',
    'timezoneOffset': 3,
    'latitude': 50.4501,
    'longitude': 30.5234,
    'houseSystem': 'P',
})

print(chart['houses']['ascendant'])

PHP - trên Guzzle 7 và PSR-18:

<?php
use Astroway\Astroway;

$aw = new Astroway(['apiKey' => getenv('ASTROWAY_API_KEY')]);

$chart = $aw->post('/chart', body: [
    'date'           => '1990-07-14',
    'time'           => '14:30:00',
    'timezoneOffset' => 3,
    'latitude'       => 50.4501,
    'longitude'      => 30.5234,
    'houseSystem'    => 'P',
]);

echo $chart['houses']['ascendant'];

Ba ngôn ngữ khác nhau nhưng cùng những đảm bảo - vì cả ba đều được tạo ra từ cùng một hợp đồng OpenAPI:

• Kiểu dữ liệu request và response cho tất cả các endpoints. TS cung cấp tự động hoàn thiện đường dẫn và các body được type hóa; Python là typed-package PEP 561; PHP là các signature được type hóa. IDE gợi ý các trường, không phải tài liệu trong tab bên cạnh.
• Retry với backoff tích hợp cho các lỗi 408, 409, 429, 5xx. Sự cố mạng tạm thời hoặc rate-limit không làm hỏng code của bạn - client tự động retry.
• Thứ bậc lỗi theo kiểu Stainless. Các lỗi được type hóa theo lớp, không phải chuỗi trong catch. Bạn bắt được kiểu cụ thể - RateLimitError, ValidationError - và xử lý điểm đến.
• OpenAPI 3.1 làm nguồn. Thêm endpoint vào API - nó sẽ xuất hiện trong SDK trong bản release tiếp theo, không cần sao chép thủ công.
• OIDC + SLSA-provenance khi xuất bản: TS và PHP qua Trusted Publisher / auto-mirror, Python qua Trusted Publisher OIDC trên PyPI. Chuỗi cung cấp có thể kiểm tra.

Base URL cho tất cả là https://api.astroway.info/v1/, key được truyền qua header X-Api-Key. Cùng key cho các HTTP call thô; SDK không thay đổi gì trong việc xác thực.

Trên ba SDK cơ bản có các tích hợp sẵn cho các stack cụ thể:

• @astroway/react - hooks cho ứng dụng React
• astroway/sdk-symfony - bundle cho Symfony
• astroway/sdk-laravel - package cho Laravel

Đang trong quá trình làm việc nhưng chưa xuất bản - Go, Ruby và Rust. Trang của họ đã có trong danh mục SDK với preview lệnh cài đặt; khi package được đăng lên registry, trạng thái thay thành ‘có sẵn’.

1. Key tại dashboard/sign-up - 10 000 credits mỗi tháng miễn phí
2. Cài SDK bằng ngôn ngữ của bạn (các lệnh trên)
3. Lệnh gọi đầu tiên - birth chart với snippet trên, thay key của bạn vào ASTROWAY_API_KEY

Danh sách đầy đủ các SDK với ví dụ cho từng ngôn ngữ - tại trang SDK.