Utilisation du SDK Python (zinn-sdk)

zinn-sdk est notre client Python officiel pour l’API Zinn Digital®, publié sur PyPI et importé sous le nom zinn_sdk. Il est généré à partir de la même spécification OpenAPI que celle utilisée pour concevoir l’API, chaque opération dispose de variantes synchrones et asyncio, et une nouvelle version est publiée automatiquement dès que la spécification change. Ce guide vous permet de l’installer, de l’authentifier et d’effectuer vos premiers appels.

Installer

pip install zinn-sdk

Elle nécessite Python 3.11 ou version ultérieure et est sous licence MIT.

Créer une clé d’API

Ouvrez la page Clés d’API de votre tableau de bord (app.zinndigital.com/api-keys) et appuyez sur Créer une clé. Donnez un nom à la clé et attribuez-lui uniquement les autorisations dont votre code a besoin — par exemple sites.view pour lister les sites. La clé n’est affichée qu’une seule fois ; stockez-la dans une variable d’environnement ou dans votre gestionnaire de secrets, jamais dans le code source. Vous pouvez révoquer une clé à tout moment sur la même page.

Les points de terminaison publics du catalogue, tels que les régions d’hébergement et les forfaits, ne nécessitent aucune clé.

Vos premiers appels

import os

from zinn_sdk import AuthenticatedClient, Client
from zinn_sdk.api.catalog import list_public_hosting_regions
from zinn_sdk.api.hosting import list_sites

# Public catalogue endpoints need no key.
public = Client(base_url="https://api.zinndigital.com")
regions = list_public_hosting_regions.sync(client=public)
print([region.slug for region in regions.data])

# Everything else uses a per-organisation API key.
api = AuthenticatedClient(base_url="https://api.zinndigital.com", token=os.environ["ZINN_API_KEY"])
page = list_sites.sync(client=api, limit=5)
for site in page.data:
    print(site.name, site.status)

Trouver une opération

Les opérations sont regroupées par domaine d’API sous zinn_sdk.api et nommées d’après leur identifiant d’opération en snake case. Lister les sites correspond à zinn_sdk.api.hosting.list_sites ; les domaines et le DNS se trouvent sous zinn_sdk.api.domains ; la facturation sous zinn_sdk.api.billing. La référence de l’API indique l’identifiant de chaque opération.

Synchrone, asynchrone et réponse complète

Chaque module d’opération comporte quatre fonctions :

• sync(...) renvoie le modèle analysé, ou None en cas de statut inattendu.
• sync_detailed(...) renvoie une Response avec status_code, headers et parsed.
• asyncio(...) et asyncio_detailed(...) sont identiques, mais awaitable.

import asyncio

from zinn_sdk.api.hosting import list_sites

async def main() -> None:
    response = await list_sites.asyncio_detailed(client=api, limit=5)
    print(response.status_code, len(response.parsed.data))

asyncio.run(main())

Utilisez les variantes _detailed lorsque vous devez distinguer un 403 (la clé ne dispose pas d’une autorisation) d’un 404.

Où aller ensuite

• Le guide sur notre site web : zinndigital.com/developers/sdk-python
• Chaque point de terminaison, ses paramètres et son autorisation : zinndigital.com/developers/api
• Le package sur PyPI : pypi.org/project/zinn-sdk