Trzy oficjalne SDK: TypeScript, Python i PHP zamiast surowego curl

Można korzystać z API przez surowy curl albo fetch: kontrakt jest prosty, jeden nagłówek X-Api-Key, JSON w obie strony. Ale gdy endpointów jest ponad 761, a treści żądań mają po kilkanaście pól, typowany klient oszczędza godziny: podpowiadanie ścieżek, typy żądań i odpowiedzi, automatyczne ponawianie przy niestabilnej sieci.

Dlatego mamy trzy oficjalne SDK, wygenerowane z jednego kontraktu OpenAPI 3.1.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

To samo wywołanie horoskopu urodzeniowego w trzech językach.

TypeScript - cienka nakładka na openapi-fetch (~6 KB runtime), z podpowiadaniem ścieżek:

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 - synchroniczny Astroway i asynchroniczny AsyncAstroway z identycznym interfejsem, oparte na 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 - na bazie Guzzle 7 i 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'];

Trzy różne języki, ale te same gwarancje, bo wszystkie trzy są generowane z tego samego kontraktu OpenAPI:

• Typy żądań i odpowiedzi dla wszystkich endpointów. TS daje podpowiadanie ścieżek i typowane treści żądań; Python to typowany pakiet zgodny z PEP 561; PHP ma typowane sygnatury. Pola podpowiada IDE, a nie dokumentacja w sąsiedniej karcie.
• Wbudowany retry z backoffem dla 408, 409, 429, 5xx. Chwilowa awaria sieci albo rate limit nie wywraca twojego kodu, klient sam ponawia żądanie.
• Hierarchia błędów w stylu Stainless. Błędy są typowane klasami, a nie są napisem w catch. Łapiesz konkretny typ, np. RateLimitError albo ValidationError, i obsługujesz go punktowo.
• OpenAPI 3.1 jako źródło. Dodany do API endpoint pojawia się w SDK w następnym wydaniu, bez ręcznego powielania.
• OIDC + provenance SLSA przy publikacji: TS i PHP przez Trusted Publisher / auto-mirror, Python przez Trusted Publisher OIDC na PyPI. Łańcuch dostaw da się zweryfikować.

Base URL jest wszędzie taki sam, https://api.astroway.info/v1/, a klucz przekazuje się w nagłówku X-Api-Key. To ten sam klucz co przy surowych wywołaniach HTTP; SDK niczego nie zmienia w autoryzacji.

Na bazie trzech podstawowych SDK są gotowe integracje pod konkretne stacki:

• @astroway/react - hooki dla aplikacji React
• astroway/sdk-symfony - bundle dla Symfony
• astroway/sdk-laravel - pakiet dla Laravela

W przygotowaniu, ale jeszcze nieopublikowane: Go, Ruby i Rust. Ich strony są już w katalogu SDK z podglądem polecenia instalacji; gdy pakiet trafi do rejestru, status zmieni się na “dostępny”.

1. Klucz na dashboard/sign-up - 10 000 kredytów miesięcznie za darmo
2. Zainstaluj SDK w swoim języku (polecenia powyżej)
3. Pierwsze wywołanie: horoskop urodzeniowy ze snippetu powyżej, wstaw swój klucz do ASTROWAY_API_KEY

Pełna lista SDK z przykładami dla każdego jest na stronie SDK.