세 가지 공식 SDK: 순수 curl 대신 TypeScript, Python, PHP

순수 curl이나 fetch로 API를 호출해도 됩니다. 계약은 단순해서 X-Api-Key 헤더 하나와 JSON 요청/응답이 전부입니다. 하지만 엔드포인트가 865개가 넘고 요청 본문에 필드가 열 개씩 있다면, 타입이 있는 클라이언트가 몇 시간을 아껴 줍니다: 경로 자동 완성, 요청과 응답 타입, 불안정한 네트워크에서의 자동 재시도.

그래서 우리는 하나의 OpenAPI 3.1 계약에서 생성한 세 가지 공식 SDK를 제공합니다.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

같은 출생 차트 호출을 세 가지 언어로 작성했습니다.

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: 동기 Astroway와 비동기 AsyncAstroway가 동일한 인터페이스를 제공하며, 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: 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'];

언어는 셋이지만 보장하는 것은 같습니다. 세 SDK 모두 같은 OpenAPI 계약에서 생성되기 때문입니다:

• 모든 엔드포인트의 요청과 응답 타입. TS는 경로 자동 완성과 타입이 있는 본문을, Python은 PEP 561 typed 패키지를, PHP는 타입이 있는 시그니처를 제공합니다. 옆 탭의 문서가 아니라 IDE가 필드를 알려 줍니다.
• backoff가 적용된 내장 재시도: 408, 409, 429, 5xx. 일시적인 네트워크 장애나 rate limit 때문에 코드가 실패하지 않습니다. 클라이언트가 알아서 재시도합니다.
• Stainless 스타일의 오류 계층. 오류는 catch 안의 문자열이 아니라 클래스로 구분됩니다. RateLimitError, ValidationError처럼 구체적인 타입을 잡아서 정확하게 처리할 수 있습니다.
• 소스는 OpenAPI 3.1. API에 엔드포인트가 추가되면 수작업 복제 없이 다음 릴리스에서 SDK에도 나타납니다.
• 배포 시 OIDC + SLSA 출처 증명(provenance): TS와 PHP는 Trusted Publisher / auto-mirror를 통해, Python은 PyPI의 Trusted Publisher OIDC를 통해 배포됩니다. 공급망을 검증할 수 있습니다.

모든 SDK의 Base URL은 https://api.astroway.info/v1/이며, 키는 X-Api-Key 헤더로 전달합니다. 순수 HTTP 호출에 쓰는 것과 같은 키이며, SDK는 인증 방식을 전혀 바꾸지 않습니다.

세 가지 기본 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 페이지에 있습니다.