Tre SDK ufficiali: TypeScript, Python e PHP al posto del curl grezzo

Puoi chiamare l’API con un semplice curl o fetch: il contratto è semplice, un solo header X-Api-Key e JSON in entrata e in uscita. Ma quando gli endpoint sono più di 865 e i body delle richieste hanno una decina di campi, un client tipizzato fa risparmiare ore: autocompletamento dei percorsi, tipi di richiesta e risposta, retry automatici su una rete instabile.

Per questo abbiamo tre SDK ufficiali, generati da un unico contratto OpenAPI 3.1.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

La stessa chiamata per il tema natale in tre linguaggi.

TypeScript: un wrapper leggero sopra openapi-fetch (~6 KB di runtime), con autocompletamento dei percorsi:

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 sincrono e AsyncAstroway asincrono con un’interfaccia identica, basati su 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: basato su Guzzle 7 e 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'];

Tre linguaggi diversi, ma le stesse garanzie, perché tutti e tre sono generati dallo stesso contratto OpenAPI:

• Tipi di richiesta e risposta per tutti gli endpoint. TS offre l’autocompletamento dei percorsi e body tipizzati; Python è un pacchetto tipizzato PEP 561; PHP ha firme tipizzate. È l’IDE a suggerirti i campi, non la documentazione nella scheda accanto.
• Retry integrato con backoff su 408, 409, 429, 5xx. Un errore di rete temporaneo o un rate limit non fanno crollare il tuo codice: il client ripete la richiesta da solo.
• Gerarchia di errori in stile Stainless. Gli errori sono tipizzati per classe, non una stringa nel catch. Intercetti un tipo specifico, come RateLimitError o ValidationError, e lo gestisci in modo mirato.
• OpenAPI 3.1 come fonte. Aggiungiamo un endpoint all’API e compare nell’SDK al rilascio successivo, senza duplicazioni manuali.
• Provenienza OIDC + SLSA sulle pubblicazioni: TS e PHP tramite Trusted Publisher / auto-mirror, Python tramite Trusted Publisher OIDC su PyPI. La supply chain è verificabile.

Il base URL è lo stesso per tutti: https://api.astroway.info/v1/, e la chiave si passa nell’header X-Api-Key. È la stessa chiave delle chiamate HTTP grezze; l’SDK non cambia nulla nell’autenticazione.

Sopra i tre SDK di base ci sono integrazioni pronte per stack specifici:

• @astroway/react: hook per applicazioni React
• astroway/sdk-symfony: bundle per Symfony
• astroway/sdk-laravel: pacchetto per Laravel

In lavorazione, ma non ancora pubblicati: Go, Ruby e Rust. Le loro pagine sono già nel catalogo SDK con l’anteprima del comando di installazione; quando il pacchetto arriva nel registry, lo stato passa a “disponibile”.

1. Ottieni la chiave su dashboard/sign-up: 10 000 crediti al mese gratis
2. Installa l’SDK nel tuo linguaggio (comandi sopra)
3. Prima chiamata: il tema natale dello snippet qui sopra, con la tua chiave in ASTROWAY_API_KEY

L’elenco completo degli SDK con esempi per ciascuno è nella pagina SDK.