Tři oficiální SDK: TypeScript, Python, PHP místo holého curl

Volat API přes holý curl nebo fetch se dá: kontrakt je jednoduchý, jedna hlavička X-Api-Key, JSON tam a zpět. Jenže když je endpointů přes 761 a těla požadavků mají desítku polí, typovaný klient ušetří hodiny: doplňování cest, typy požadavku i odpovědi, automatické opakování na nestabilní síti.

Proto máme tři oficiální SDK vygenerovaná z jednoho OpenAPI 3.1 kontraktu.

# TypeScript / JavaScript
npm install @astroway/sdk

# Python
pip install astroway

# PHP
composer require astroway/sdk

Totéž volání natálního horoskopu ve třech jazycích.

TypeScript: tenká vrstva nad openapi-fetch (~6 KB runtime) s doplňováním cest:

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: synchronní Astroway a asynchronní AsyncAstroway se stejným rozhraním, postavené na 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: postavené na Guzzle 7 a 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'];

Tři různé jazyky, ale stejné záruky, protože všechna tři se generují ze stejného OpenAPI kontraktu:

• Typy požadavku i odpovědi pro všechny endpointy. TS nabízí doplňování cest a typovaná těla; Python je typovaný balíček podle PEP 561; PHP má typované signatury. Pole ti napovídá IDE, ne dokumentace ve vedlejší záložce.
• Vestavěný retry s backoffem na 408, 409, 429, 5xx. Dočasný výpadek sítě nebo rate limit tvůj kód neshodí, klient to zopakuje sám.
• Hierarchie chyb ve stylu Stainless. Chyby jsou typované třídami, ne řetězec v catch. Chytáš konkrétní typ, RateLimitError, ValidationError, a ošetříš ho cíleně.
• OpenAPI 3.1 jako zdroj. Přibude endpoint v API a v SDK se objeví v příštím vydání, bez ručního duplikování.
• OIDC + SLSA provenance při publikaci: TS a PHP přes Trusted Publisher / auto-mirror, Python přes Trusted Publisher OIDC na PyPI. Dodavatelský řetězec je ověřitelný.

Base URL je všude https://api.astroway.info/v1/, klíč se předává hlavičkou X-Api-Key. Je to tentýž klíč jako pro holá HTTP volání; SDK na autorizaci nic nemění.

Nad třemi základními SDK jsou hotové integrace pro konkrétní stacky:

• @astroway/react: hooky pro React aplikace
• astroway/sdk-symfony: bundle pro Symfony
• astroway/sdk-laravel: balíček pro Laravel

Rozpracované, ale zatím nepublikované jsou Go, Ruby a Rust. Jejich stránky už v katalogu SDK jsou s náhledem instalačního příkazu; jakmile balíček vyjde v registry, stav se změní na “dostupné”.

1. Klíč na dashboard/sign-up: 10 000 kreditů měsíčně zdarma
2. Nainstaluj SDK pro svůj jazyk (příkazy výše)
3. První volání: natální horoskop ze snippetu výše, dosaď svůj klíč do ASTROWAY_API_KEY

Kompletní seznam SDK s příklady pro každé najdeš na stránce SDK.