Három hivatalos SDK: TypeScript, Python, PHP a nyers curl helyett

Az API-hoz nyers curl vagy fetch használatával is lehet menni – a szerződés egyszerű, egy X-Api-Key fejléc, JSON oda‑vissza. De amikor az endpointok száma meghaladja a 758 értéket, és a kérések testjei tucatnyi mezőt tartalmaznak, a típusos kliens órákat takarít meg: útvonalak automatikus kiegészítése, kérés‑ és válasz típusok, automatikus újrapróbálkozások instabil hálózaton.

Ezért három hivatalos SDK-unk van, amely egy OpenAPI 3.1 szerződésből generálódik.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

Ugyanaz a születési képlet hívása három nyelven.

TypeScript – egy vékony réteg a openapi-fetch felett (~6 KB runtime), útvonalak automatikus kiegészítésével:

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 – szinkron Astroway és aszinkron AsyncAstroway azonos felülettel, a httpx felett:

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 – a Guzzle 7 és PSR‑18 felett:

<?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'];

Három különböző nyelv, de ugyanazok a garanciák – mert mindhárom ugyanabból az OpenAPI szerződésből generálódik:

• Kérés- és válasz típusok minden endpointhoz. TS útvonalak automatikus kiegészítését és típusos testeket biztosít; Python – PEP 561 típusos csomag; PHP – típusos szignatúrák. Az IDE a mezőket javasolja, nem a dokumentációt egy külön fülön.
• Beépített újrapróbálkozás backoff‑dal a 408, 409, 429, 5xx esetén. Egy átmeneti hálózati hiba vagy rate‑limit nem rombolja a kódod – a kliens magától újrapróbálja.
• Stainless‑style hibahierarchia. A hibák osztályok szerint vannak típusosítva, nem sztringként a catch‑ben. Elkapod a konkrét típust – RateLimitError, ValidationError – és célzottan kezeled.
• OpenAPI 3.1 mint forrás. Ha egy endpointot hozzáadsz az API‑hoz, az a következő kiadásban megjelenik az SDK‑ban, manuális duplikáció nélkül.
• OIDC + SLSA‑provenance a kiadáskor: TS és PHP – Trusted Publisher / auto‑mirror segítségével, Python – Trusted Publisher OIDC a PyPI‑n. A szállítási lánc ellenőrizhető.

Az összes esetben a Base URL – https://api.astroway.info/v1/, a kulcs a X-Api-Key fejlécben kerül átadásra. Ugyanaz a kulcs, mint a nyers HTTP hívásoknál; az SDK semmit sem változtat a hitelesítésen.

A három alap SDK felett kész integrációk vannak konkrét stackekhez:

• @astroway/react – hookok React‑alkalmazásokhoz
• astroway/sdk-symfony – bundle Symfony‑hoz
• astroway/sdk-laravel – csomag Laravel‑hez

Fejlesztés alatt, de még nem kiadott – Go, Ruby és Rust. Az oldalaik már megtalálhatók az SDK katalógusban a telepítési parancs előnézetével; amikor a csomag megjelenik a registry‑ben, a státusz „elérhető” lesz.

1. Kulcs a dashboard/sign-up oldalon – 10 000 kredit havonta ingyen
2. Telepítsd az SDK‑t a saját nyelveden (a fenti parancsok)
3. Első hívás – a születési képlet a fenti snippet‑ből, helyettesítsd be a saját kulcsod a ASTROWAY_API_KEY‑ba

A teljes SDK lista példákkal mindenhez – a SDK oldalon.