3つの公式SDK: TypeScript、Python、PHP - 生のcurlの代わりに

生のcurlやfetchでAPIにアクセスすることは可能だ。契約はシンプルで、X-Api-Keyヘッダーが1つ、JSONの送受信だけだ。しかし、エンドポイントが758を超え、リクエストボディに数十のフィールドがある場合、型付きクライアントは何時間もの時間を節約してくれる。パスの自動補完、リクエストとレスポンスの型、不安定なネットワークでの自動リトライなどだ。

そのため、私たちは単一のOpenAPI 3.1コントラクトから生成された3つの公式SDKを提供している。

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

同じ出生図の呼び出しを3つの言語で。

TypeScript - openapi-fetch (~6 KBランタイム) の薄いラッパーで、パスの自動補完機能付き:

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 - httpxをベースにした、同期Astrowayと非同期AsyncAstrowayで、同一のインターフェースを持つ:

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 - Guzzle 7と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'];

3つの異なる言語だが、すべて同じOpenAPIコントラクトから生成されているため、同じ保証がある:

• すべてのエンドポイントに対するリクエストとレスポンスの型。 TSはパスの自動補完と型付きボディを提供し、PythonはPEP 561の型付きパッケージ、PHPは型付きシグネチャを提供する。IDEがフィールドを提案してくれるので、隣のタブでドキュメントを確認する必要はない。
• 408、409、429、5xxに対するバックオフ付き組み込みリトライ。 一時的なネットワーク障害やレート制限によってコードがクラッシュすることはない。クライアントが自動的にリトライする。
• Stainlessスタイルのエラー階層。 エラーはcatch内の文字列ではなく、クラスで型付けされている。RateLimitErrorやValidationErrorといった特定の型をキャッチし、ピンポイントで処理できる。
• OpenAPI 3.1をソースとして。 APIにエンドポイントを追加すると、手動で重複させることなく、次のリリースでSDKに反映される。
• 公開時のOIDC + SLSAプロベナンス: TSとPHPはTrusted Publisher / auto-mirror経由、PythonはPyPI上のTrusted Publisher OIDC経由。サプライチェーンは検証可能だ。

すべてのベースURLはhttps://api.astroway.info/v1/で、キーはX-Api-Keyヘッダーで渡される。これは生のHTTP呼び出しと同じキーであり、SDKは認証に関して何も変更しない。

3つの基本SDKの上に、特定のスタック向けの統合が用意されている:

• @astroway/react - Reactアプリケーション用のフック
• astroway/sdk-symfony - Symfony用バンドル
• astroway/sdk-laravel - Laravel用パッケージ

Go、Ruby、Rustは開発中だが、まだ公開されていない。SDKカタログにはすでにプレビューのインストールコマンド付きでページがある。パッケージがレジストリに公開されると、ステータスは「利用可能」に変わる。

1. dashboard/sign-upでキーを取得 - 月10,000クレジットが無料
2. 自分の言語でSDKをインストール (上記のコマンド)
3. 最初の呼び出し - 上記のスニペットにある出生図で、ASTROWAY_API_KEYに自分のキーを代入する

各SDKの完全なリストと例は、SDKページで確認できる。