Τρία επίσημα SDK: TypeScript, Python, PHP αντί για ακατέργαστο curl

Μπορείς να καλέσεις το API με ακατέργαστο curl ή fetch – η σύμβαση είναι απλή, ένα header X-Api-Key, JSON μπρος-πίσω. Αλλά όταν τα endpoints είναι πάνω από 758 και τα σώματα των αιτημάτων έχουν δεκάδες πεδία, ένας τυποποιημένος client σου εξοικονομεί ώρες: αυτόματη συμπλήρωση διαδρομών, τύποι αιτήματος και απάντησης, αυτόματες επαναλήψεις σε ασταθή δίκτυο.

Γι’ αυτό έχουμε τρία επίσημα SDK, που δημιουργήθηκαν από ένα OpenAPI 3.1 contract.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

Η ίδια κλήση για το natal chart με τρεις γλώσσες.

TypeScript – ελαφριά επικάλυψη πάνω από openapi-fetch (~6 KB runtime), με αυτόματη συμπλήρωση διαδρομών:

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 και ασύγχρονο AsyncAstroway με ίδια διεπαφή, πάνω από 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 – πάνω από Guzzle 7 και 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'];

Τρεις διαφορετικές γλώσσες, αλλά ίσες εγγυήσεις – επειδή και οι τρεις δημιουργούνται από το ίδιο OpenAPI contract:

• Τύποι αιτήματος και απάντησης για όλα τα endpoints. Το TS παρέχει αυτόματη συμπλήρωση διαδρομών και τυποποιημένα σώματα· Python – PEP 561 typed‑πακέτο· PHP – τυποποιημένες υπογραφές. Το IDE σου προτείνει πεδία, όχι τεκμηρίωση σε άλλη καρτέλα.
• Ενσωματωμένο retry με backoff στα 408, 409, 429, 5xx. Ένα προσωρινό σφάλμα δικτύου ή rate‑limit δεν σπάει τον κώδικά σου – ο client επαναλαμβάνει αυτόματα.
• Ιεραρχία σφαλμάτων σε στυλ Stainless. Τα σφάλματα τυποποιούνται με κλάσεις, όχι με συμβολοσειρά στο catch. Πιάνεις συγκεκριμένο τύπο – RateLimitError, ValidationError – και το διαχειρίζεσαι επιλεκτικά.
• OpenAPI 3.1 ως πηγή. Προσθέτεις ένα endpoint στο API – εμφανίζεται στο SDK στην επόμενη έκδοση, χωρίς χειροκίνητη αντιγραφή.
• OIDC + SLSA provenance στην έκδοση: TS και PHP – μέσω Trusted Publisher / auto‑mirror, Python – Trusted Publisher OIDC στο PyPI. Η αλυσίδα εφοδιασμού είναι επαληθεύσιμη.

Base URL σε όλα – https://api.astroway.info/v1/, το κλειδί περνάει ως header X-Api-Key. Το ίδιο κλειδί όπως στα ακατέργαστα HTTP calls· το SDK δεν αλλάζει τίποτα στην εξουσιοδότηση.

Πάνω από τα τρία βασικά SDK υπάρχουν έτοιμες ενσωματώσεις για συγκεκριμένα stack:

• @astroway/react – hooks για εφαρμογές React
• astroway/sdk-symfony – bundle για Symfony
• astroway/sdk-laravel – πακέτο για Laravel

Σε ανάπτυξη, αλλά ακόμη μη δημοσιευμένα – Go, Ruby και Rust. Οι σελίδες τους υπάρχουν ήδη στον κατάλογο SDK με preview της install‑εντολής· όταν το πακέτο βγει στο registry, η κατάσταση αλλάζει σε «διαθέσιμο».

1. Κλειδί στο dashboard/sign-up – 10 000 credits το μήνα δωρεάν
2. Εγκατέστησε το SDK στη γλώσσα σου (εντολές παραπάνω)
3. Πρώτη κλήση – natal chart από το snippet παραπάνω, βάλε το κλειδί σου στο ASTROWAY_API_KEY

Πλήρης λίστα SDK με παραδείγματα για καθένα – στη σελίδα SDK.