Trei SDK-uri oficiale: TypeScript, Python și PHP în loc de curl simplu

Poți apela API-ul cu curl sau fetch simplu: contractul este simplu, un singur header X-Api-Key și JSON în ambele sensuri. Dar când există peste 865 endpoint-uri, iar corpurile cererilor au o duzină de câmpuri, un client tipizat economisește ore: autocompletare pentru căi, tipuri de cerere și răspuns, reîncercări automate pe o rețea instabilă.

De aceea avem trei SDK-uri oficiale, generate dintr-un singur contract OpenAPI 3.1.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

Același apel pentru harta natală, în trei limbaje.

TypeScript: un wrapper subțire peste openapi-fetch (~6 KB de runtime), cu autocompletare pentru căi:

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 sincron și AsyncAstroway asincron, cu aceeași suprafață, peste 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: peste 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'];

Trei limbaje diferite, dar aceleași garanții, pentru că toate trei sunt generate din același contract OpenAPI:

• Tipuri de cerere și răspuns pentru toate endpoint-urile. TS oferă autocompletare pentru căi și corpuri tipizate; Python este un pachet tipizat PEP 561; PHP are semnături tipizate. Câmpurile ți le sugerează IDE-ul, nu documentația din tabul alăturat.
• Retry integrat cu backoff la 408, 409, 429, 5xx. O cădere temporară de rețea sau un rate limit nu îți dărâmă codul: clientul reîncearcă singur.
• Ierarhie de erori în stil Stainless. Erorile sunt tipizate pe clase, nu un șir de caractere într-un catch. Prinzi un tip concret, RateLimitError sau ValidationError, și îl tratezi punctual.
• OpenAPI 3.1 ca sursă. Un endpoint adăugat în API apare în SDK la următoarea versiune, fără duplicare manuală.
• OIDC + proveniență SLSA la publicare: TS și PHP prin Trusted Publisher / auto-mirror, Python prin Trusted Publisher OIDC pe PyPI. Lanțul de aprovizionare este verificabil.

Base URL-ul este același peste tot, https://api.astroway.info/v1/, iar cheia se trimite în header-ul X-Api-Key. Este aceeași cheie ca pentru apelurile HTTP simple; SDK-ul nu schimbă nimic la autorizare.

Peste cele trei SDK-uri de bază există integrări gata făcute pentru stack-uri concrete:

• @astroway/react: hook-uri pentru aplicații React
• astroway/sdk-symfony: bundle pentru Symfony
• astroway/sdk-laravel: pachet pentru Laravel

În lucru, dar încă nepublicate: Go, Ruby și Rust. Paginile lor sunt deja în catalogul de SDK-uri, cu o previzualizare a comenzii de instalare; când pachetul apare în registry, statusul devine “disponibil”.

1. Cheie pe dashboard/sign-up: 10 000 de credite pe lună gratuit
2. Instalează SDK-ul în limbajul tău (comenzile de mai sus)
3. Primul apel: harta natală din fragmentul de mai sus, cu cheia ta în ASTROWAY_API_KEY

Lista completă de SDK-uri, cu exemple pentru fiecare, este pe pagina SDK.