Tre SDK ufficiali: TypeScript, Python, PHP invece di curl grezzo

È possibile utilizzare l’API attraverso curl o fetch - il contratto è semplice, un solo header X-Api-Key, JSON a entrambi i sensi. Tuttavia, quando si hanno più di 758 endpoint, e i corpi delle richieste hanno una decina di campi, un client tipizzato risparmia ore: autocompletamento dei percorsi, tipi di richiesta e risposta, ripetizioni automatiche in una rete instabile.

Per questo motivo, abbiamo tre SDK ufficiali, generate dallo stesso contratto OpenAPI 3.1.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

Lo stesso richiamo della carta natale in tre lingue.

TypeScript - sottile involucro sopra openapi-fetch (~6 KB 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 - sincrono Astroway e asincrono AsyncAstroway con superficie identica, sopra 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 - sopra 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 lingue diverse, ma garanzie identiche - perché tutti e tre sono generati dallo stesso contratto OpenAPI:

• Tipi di richiesta e risposta per tutti gli endpoint. TS fornisce autocompletamento dei percorsi e corpi tipizzati; Python - PEP 561 typed-pacchetto; PHP - tipi di segnatura. L’IDE suggerisce i campi, e non la documentazione nella finestra accanto.
• Ripetizioni automatiche con backoff su 408, 409, 429, 5xx. Un temporaneo guasto di rete o un limite di velocità non farà cadere il tuo codice - il client ripete da solo.
• Stile Stainless e gerarchia degli errori. Gli errori sono tipizzati per classe, e non una stringa in catch. Capi di richiamo specifico - RateLimitError, ValidationError - e trattano con precisione.
• OpenAPI 3.1 come fonte. Aggiungi un endpoint all’API - compare nello stesso SDK al prossimo rilascio, senza duplicazione manuale.
• OIDC + SLSA-provenienza per le pubblicazioni: TS e PHP - attraverso Trusted Publisher / auto-mirror, Python - Trusted Publisher OIDC su PyPI. La catena di fornitura è verificata.

Base URL in tutti - https://api.astroway.info/v1/, chiave trasmessa attraverso il header X-Api-Key. Lo stesso chiave che per i richiami HTTP sincroni; lo SDK non modifica l’autenticazione.

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

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

In lavorazione, ma ancora non pubblicati - Go, Ruby e Rust. Le loro pagine sono già nel catalogo SDK con la previsione dell’installazione; quando il pacchetto esce nel registro, lo stato cambia a “disponibile”.

1. Chiave su dashboard/sign-up - 10.000 crediti al mese gratuitamente
2. Installa lo SDK nella tua lingua (comandi sopra)
3. Primo richiamo - carta natale con snippet sopra, sostituisci la tua chiave in ASTROWAY_API_KEY

Elenco completo di SDK con esempi per ciascuno - sulla pagina SDK.