De Python SDK (zinn-sdk) gebruiken

zinn-sdk is onze officiële Python-client voor de Zinn Digital®-API, gepubliceerd op PyPI en geïmporteerd als zinn_sdk. Deze is gegenereerd op basis van dezelfde OpenAPI-specificatie als waar de API op is gebouwd, elke bewerking heeft synchrone en asyncio-varianten, en er wordt automatisch een nieuwe versie gepubliceerd wanneer de specificatie verandert. Deze handleiding installeert de client, verifieert deze en voert uw eerste aanroepen uit.

Installeren

pip install zinn-sdk

Het vereist Python 3.11 of nieuwer en is gelicentieerd onder de MIT-licentie.

Een API-sleutel aanmaken

Open de pagina API-sleutels van uw dashboard (app.zinndigital.com/api-keys) en druk op Een sleutel aanmaken. Geef de sleutel een naam en verleen alleen de rechten die uw code nodig heeft — bijvoorbeeld sites.view om sites op te sommen. De sleutel wordt eenmalig getoond; sla deze op in een omgevingsvariabele of uw geheime opslag, nooit in de broncode. U kunt een sleutel op elk gewenst moment intrekken op dezelfde pagina.

Openbare catalogus-eindpunten, zoals hostingregio's en -abonnementen, hebben helemaal geen sleutel nodig.

Uw eerste aanroepen

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)

Een bewerking zoeken

Bewerkingen zijn gegroepeerd per API-gebied onder zinn_sdk.api en genoemd naar hun bewerkings-id in snake case. Sites weergeven is zinn_sdk.api.hosting.list_sites; domeinen en DNS vallen onder zinn_sdk.api.domains; facturering onder zinn_sdk.api.billing. De API-referentie toont de id van elke bewerking.

Sync, async en de volledige respons

Elke bewerkingsmodule heeft vier functies:

• sync(...) retourneert het geparseerde model, of None bij een onverwachte status.
• sync_detailed(...) retourneert een Response met status_code, headers en parsed.
• asyncio(...) en asyncio_detailed(...) zijn hetzelfde, 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())

Gebruik de _detailed-varianten wanneer u een 403 (de sleutel mist een machtiging) moet onderscheiden van een 404.

Waar u vervolgens naartoe kunt gaan

• De handleiding op onze website: zinndigital.com/developers/sdk-python
• Elk eindpunt, de bijbehorende parameters en de bijbehorende machtiging: zinndigital.com/developers/api
• Het pakket op PyPI: pypi.org/project/zinn-sdk