Χρήση του TypeScript SDK (@zinn-digital/sdk)

Το @zinn-digital/sdk είναι το επίσημο TypeScript client μας για το Zinn Digital® API, το οποίο έχει δημοσιευτεί στο npm. Κάθε διαδρομή, παράμετρος και απόκριση σε αυτό παράγεται από την ίδια προδιαγραφή OpenAPI από την οποία έχει δημιουργηθεί το API, και μια νέα έκδοση δημοσιεύεται αυτόματα κάθε φορά που αλλάζει αυτή η προδιαγραφή. Αυτός ο οδηγός το εγκαθιστά, πραγματοποιεί τον έλεγχο ταυτότητάς του και εκτελεί τις πρώτες σας κλήσεις.

Εγκατάσταση

npm install @zinn-digital/sdk

Λειτουργεί σε οποιοδήποτε περιβάλλον εκτέλεσης JavaScript που διαθέτει fetch: Node.js, το πρόγραμμα περιήγησης και περιβάλλοντα εκτέλεσης edge. Έχει μία εξάρτηση χρόνου εκτέλεσης, το openapi-fetch, και διαθέτει άδεια χρήσης MIT.

Δημιουργία κλειδιού API

Ανοίξτε τη σελίδα Κλειδιά API του πίνακα ελέγχου σας (app.zinndigital.com/api-keys) και πατήστε Δημιουργία κλειδιού. Δώστε ένα όνομα στο κλειδί και μόνο τα δικαιώματα που χρειάζεται ο κώδικάς σας — για παράδειγμα sites.view για την προβολή λίστας ιστοτόπων. Το κλειδί εμφανίζεται μόνο μία φορά· αποθηκεύστε το σε μια μεταβλητή περιβάλλοντος ή στο χώρο αποθήκευσης μυστικών σας, ποτέ στον πηγαίο κώδικα. Μπορείτε να ανακαλέσετε ένα κλειδί ανά πάσα στιγμή στην ίδια σελίδα.

Τα δημόσια τελικά σημεία καταλόγου, όπως οι περιοχές και τα προγράμματα φιλοξενίας, δεν χρειάζονται καθόλου κλειδί.

Οι πρώτες σας κλήσεις

import { createApiClient } from "@zinn-digital/sdk";

const api = createApiClient({ baseUrl: "https://api.zinndigital.com" });

// Public catalogue endpoints need no key.
const { data: regions } = await api.GET("/v1/catalog/regions");
console.log(regions?.data.map((r) => r.slug));

// Everything else uses a per-organisation API key.
api.use({
  onRequest({ request }) {
    request.headers.set("Authorization", `Bearer ${process.env.ZINN_API_KEY}`);
  },
});

const { data, error } = await api.GET("/v1/sites", { params: { query: { limit: 5 } } });
if (error) throw new Error(error.error.message);
for (const site of data.data) console.log(site.name, site.status);

Εκτελέστε το με ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Η πρώτη γραμμή εκτυπώνει τις περιοχές φιλοξενίας, και στη συνέχεια μία γραμμή ανά ιστότοπο.

Τύποι για τον δικό σας κώδικα

Οι τύποι σχημάτων εξάγονται, επομένως οι δικές σας συναρτήσεις μπορούν να χρησιμοποιούν τις δομές του API:

import type { components } from "@zinn-digital/sdk";

type Site = components["schemas"]["Site"];
type DnsRecord = components["schemas"]["DnsRecord"];

Μια ανορθόγραφη διαδρομή, παράμετρος ή πεδίο αποτελεί σφάλμα μεταγλώττισης και όχι ένα αίτημα που εκτελεί σιωπηρά τη λάθος ενέργεια.

Σφάλματα

Κάθε κλήση επιστρέφει { data, error, response }. Σε απόκριση διαφορετική από 2xx, το data είναι απροσδιόριστο και το error είναι ο φάκελος σφάλματος του API: error.error.code, ένα αναγνώσιμο από τον άνθρωπο error.error.message και, για αποτυχίες επικύρωσης, το error.error.details που κατονομάζει κάθε πεδίο. Ο κωδικός 403 σημαίνει ότι το κλειδί δεν φέρει το δικαίωμα που χρειάζεται το τελικό σημείο — δημιουργήστε ένα κλειδί με αυτό το δικαίωμα αντί να επαναχρησιμοποιήσετε ένα με περισσότερα.

Επόμενα βήματα

• Ο οδηγός στον ιστότοπό μας: zinndigital.com/developers/sdk-typescript
• Κάθε τελικό σημείο, οι παράμετροί του και το δικαίωμά του: zinndigital.com/developers/api
• Το πακέτο στο npm: npmjs.com/package/@zinn-digital/sdk