Kinsta è una piattaforma cloud progettata per aiutare le aziende e i team di sviluppo a lanciare e gestire progetti web in modo più rapido ed efficiente.

Kinsta offre a sviluppatori e utenti un’API che consente loro di gestire in modo programmatico siti WordPress, applicazioni e database.

L’API di Kinsta può essere utilizzata per automatizzare attività, recuperare dati e integrare Kinsta con altre applicazioni senza accedere a MyKinsta. Per accedere all’API è necessaria una chiave API. In questo articolo spieghiamo come creare e usare una chiave API di Kinsta.

Come creare una chiave API

Per usare l’API di Kinsta, dovete avere un account con almeno un sito, un’applicazione o un database WordPress in MyKinsta. Dovrete inoltre generare una chiave API per autenticarvi e accedere al vostro account tramite l’API. Per generare una chiave API:

  1. Andate al vostro cruscotto MyKinsta.
  2. Andate alla pagina delle chiavi API (il vostro nome > Impostazioni azienda > Chiavi API).
  3. Fate clic su Crea chiave API.
  4. Scegliete una scadenza oppure impostate una data di inizio personalizzata e un numero di ore fino alla scadenza della chiave.
  5. Assegnate alla chiave un nome univoco.
  6. Fate clic su Genera.
Schermata di MyKinsta con la finestra dedicata alla creazione di una chiave API
Creare una chiave API su MyKinsta.

Quando create una chiave API, copiatela e conservatela in un posto sicuro, perché questo è l’unico momento in cui potrete vederla. Potete generare più chiavi API: saranno elencate nella pagina delle chiavi API. Se avete bisogno di revocare una chiave API, fate clic su Revoca accanto a quella che volete revocare.

Come usare l’API di Kinsta con la chiave API

Una volta ottenuta la chiave API, potete interagire con tutti i servizi di Kinsta (siti WordPress, applicazioni e database) tramite l’API di Kinsta, ad esempio per ottenere un elenco di database per ID aziendale, siti aziendali, creare un sito WordPress e altro.

Ad esempio, per ottenere un elenco dei siti dell’azienda nel vostro cruscotto MyKinsta, l’endpoint è /sites. La chiave API servirà come header di autorizzazione; dovrete inoltre aggiungere l’ID dell’azienda (parametro obbligatorio). Ecco come effettuare questa richiesta all’API usando cURL:

curl -i -X GET
  'https://api.kinsta.com/v2/sites?company='
  -H 'Authorization: Bearer <YOUR_API_KEY_HERE>'

Sostituite YOUR_API_KEY_HERE con la chiave API che avete generato e COMPANY_ID_HERE con l’ID univoco della vostra azienda. Questo restituirà una risposta JSON di tutti i siti aziendali presenti nel vostro cruscotto DevKinsta:

{
	"company": {
    	"sites": [
        	{
            	"id": "YOUR_SITE_ID",
            	"name": "my-test-site",
            	"display_name": "Test site",
            	"status": "live",
            	"site_labels": []
        	}
    	]
	}
}

Un altro esempio: supponiamo che vogliate recuperare un sito specifico per ID (richiesta GET). Potete usare l’endpoint /sites/{site_id}. {site_id} sarà sostituito dall’ID univoco del sito specifico che volete recuperare. Ecco come effettuare questa richiesta all’API utilizzando NodeJS:

import fetch from 'node-fetch';

async function fetchSite() {
  const siteId = 'YOUR_SITE_ID';
  const response = await fetch(
	`https://api.kinsta.com/v2/sites/${siteId}`,
	{
  	method: 'GET',
  	headers: {
    	Authorization: 'Bearer
  	}
	}
  );

  const data = await response.json();
  console.log(data);
}

fetchSite();

Le possibilità di utilizzo dell’API di Kinsta sono molte di più. Per tutte le informazioni sugli endpoint disponibili e sui parametri necessari, scaricare le nostre specifiche OpenAPI e provare gli endpoint, consultate la nostra API Reference.

Permessi

I permessi di accesso alle API di Kinsta dipendono dal ruolo dell’utente all’interno dell’azienda: possono creare chiavi API i proprietari, gli amministratori e gli sviluppatori.

Una chiave API generata da uno sviluppatore non avrà lo stesso livello di accesso di una chiave generata dal proprietario o dall’amministratore dell’azienda. Le autorizzazioni specifiche associate a ciascun ruolo utente garantiscono un controllo degli accessi e una sicurezza adeguati per l’API di Kinsta.

Come usare l’API di Kinsta per creare uno status checker

Quando si crea un’applicazione, un sito o un database su MyKinsta, si passa attraverso diverse fasi. Lo stato dell’applicazione permette di individuare queste fasi. Ad esempio, un’applicazione distribuita su Kinsta avrà uno stato che indica se in fase di distribuzione, se è stata distribuita con successo o se è fallita.

L’API di Kinsta fornisce endpoint che permettono di recuperare informazioni sullo stato dei progetti su MyKinsta. Per questo progetto, dovrete interagire con tre endpoint: /applications, /sites, e /databases. Potrete recuperare un array di tutte le applicazioni, i siti e i database utilizzando la Fetch API JavaScript.

Una volta recuperato l’elenco, potete usare il metodo JavaScript find() per cercare il nome di un progetto specifico inserito nell’interfaccia utente (UI). Questo metodo restituisce il nome e lo stato del progetto, se esiste.

Schermata dello status checker di Kinsta
Applicazione web di controllo dello stato.

Prerequisiti

Per seguire questo progetto, è consigliabile avere una conoscenza di base di HTML, CSS e JavaScript e una certa familiarità con React. L’obiettivo principale del progetto è mostrare l’utilizzo dell’API di Kinsta, quindi l’articolo non si addentrerà nei dettagli della creazione o dello stile dell’interfaccia utente.

Potete creare un repository Git utilizzando questo template su GitHub. Selezionate Use this template > Create a new repository per copiare il codice di partenza in un nuovo repository all’interno del vostro account GitHub e assicuratevi di selezionare la casella per includere tutti i branch. Una volta effettuato il pull sul vostro computer locale, passate alla sezione status-checker-ui per usare i file di partenza tramite questo comando:

git checkout status-checker-ui

Installate le dipendenze necessarie eseguendo il comando npm install. Una volta completata l’installazione, potete lanciare il progetto sul vostro computer locale usando il comando npm run start. Questo aprirà il progetto all’indirizzo http://localhost:3000/.

Schermata di MyKinsta per il controllo dello stato dei progetti
Controllare lo stato dei progetti MyKinsta.

Questo progetto ha due pagine principali: la Home e la pagina dei servizi. La pagina iniziale mostra un elenco dei servizi forniti da Kinsta (hosting di WordPress, applicazioni e database). Cliccando su uno dei servizi, si accede alla pagina dei servizi, che fornisce informazioni specifiche sul servizio selezionato.

Per esempio, facendo clic sulla sezione “Applicazioni”, verrete reindirizzati alla pagina dei servizi dedicata alle applicazioni. In questa pagina potete cercare qualsiasi applicazione all’interno del vostro account MyKinsta e recuperare lo stato dell’applicazione utilizzando il suo nome univoco o il nome visualizzato.

Interagire con l’API di Kinsta

Per implementare la funzione di ricerca di questo progetto, dovrete creare tre funzioni per gestire le richieste di ricerca per ogni servizio (applicazioni, siti e database). Poi, implementerete una funzionalità di ricerca che scansiona l’intero array di dati per verificare l’esistenza di un determinato valore di ricerca.

Per interagire con l’API di Kinsta avete bisogno del vostro ID azienda e della vostra chiave API, in modo da poter recuperare un elenco di database, applicazioni e siti disponibili nel vostro account MyKinsta. Una volta ottenuti questi dati, memorizzateli come variabili d’ambiente nella vostra applicazione React creando un file .env nella cartella principale del progetto.

REACT_APP_KINSTA_COMPANY_ID = 'YOUR_COMPANY_ID'
REACT_APP_KINSTA_API_KEY = 'YOUR_API_KEY'

A questo punto potrete accedere a questi valori in qualsiasi punto del progetto utilizzando process.env.THE_VARIABLE. Ad esempio, per accedere a REACT_APP_KINSTA_COMPANY_ID, potete utilizzare process.env.REACT_APP_KINSTA_COMPANY_ID.

Prima di usare l’API, create tre stati nella pagina Service.jsx per memorizzare lo stato e il nome dell’output generato quando cercate un sito, un’applicazione o un database. Il terzo stato serve a memorizzare le informazioni sugli errori.

let [status, setStatus] = useState('');
let [name, setName] = useState('');
let [error, setError] = useState('');

Create anche una variabile per memorizzare l’URL dell’API di Kinsta:

const KinstaAPIUrl = 'https://api.kinsta.com/v2';

Quindi collegate un evento onClick con una funzione CheckQuery() al pulsante di invio del modulo nella pagina Service.jsx, in modo da attivare una funzione basata sullo slug. In altre parole, se lo slug indica database, verrà attivata la funzione CheckDatabases():

const CheckQuery = async (name) => {
  if (slug === 'wp-site') {
  	await CheckSites(name);
  } else if (slug === 'application') {
  	await CheckApplications(name);
  } else if (slug === 'database') {
  	await CheckDatabases(name);
  }
}

Recuperare un elenco di siti con l’API di Kinsta

Per ottenere un elenco di siti disponibili sull’account della vostra azienda in MyKinsta con l’API di Kinsta, dovrete creare una funzione, inserire una query con l’ID dell’azienda come parametro e autorizzare la richiesta con la vostra chiave API. Questa richiesta userà l’endpoint /sites:

const CheckSites = async (name) => {
  const query = new URLSearchParams({
  	company: `${process.env.REACT_APP_KINSTA_COMPANY_ID}`,
  }).toString();
  const resp = await fetch(
  	`${KinstaAPIUrl}/sites?${query}`,
  	{
      	method: 'GET',
      	headers: {
          	Authorization: `Bearer ${process.env.REACT_APP_KINSTA_API_KEY}`
      	}
  	}
  );
}

Questo codice recupererà tutti i siti disponibili nel vostro account MyKinsta; ora potete usare il metodo find() per verificare se la query di ricerca corrisponde a un name o a un display name:

const data = await resp.json();
  let sitesData = data.company.sites;
  let site = sitesData.find(site => site.name === name || site.display_name === name);

In questo modo, potete creare alcune condizioni per verificare se il risultato è positivo, quindi impostare gli stati, altrimenti aggiornare lo stato di errore con un messaggio che informa l’utente che il sito in questione non esiste:

if (site) {
	setName(site.display_name);
	if (site.status === 'live') {
    	setStatus('🟢 Running');
	} else if (site.status === 'staging') {
    	setStatus('🟡 Staging');
	} else {
    	setStatus('🟡 Unknown');
	}
	setUniqueName('');
} else {
	setError('No such site found for your account');
	setUniqueName('');
}

Se mettete insieme tutti questi elementi, ecco come apparirà il vostro codice per verificare lo stato di un determinato sito:

const CheckSites = async (name) => {
  setName('');
  setStatus('');
  setError('');
  const query = new URLSearchParams({
  	company: `${process.env.REACT_APP_KINSTA_COMPANY_ID}`,
  }).toString();
  const resp = await fetch(
  	`${KinstaAPIUrl}/sites?${query}`,
  	{
      	method: 'GET',
      	headers: {
          	Authorization: `Bearer ${process.env.REACT_APP_KINSTA_API_KEY}`
      	}
  	}
  );
  const data = await resp.json();
  let sitesData = data.company.sites;
  let site = sitesData.find(site => site.name === name || site.display_name === name);
  if (site) {
  	setName(site.display_name);
  	if (site.status === 'live') {
      	setStatus('🟢 Running');
  	} else if (site.status === 'staging') {
      	setStatus('🟡 Staging');
  	} else {
      	setStatus('🟡 Unknown');
  	}
  	setUniqueName('');
  } else {
  	setError('No such site found for your account');
  	setUniqueName('');
  }
}

Nota: tutti e tre gli stati sono inizializzati come stringhe vuote ogni volta che la funzione CheckSites() viene attivata. Questo è necessario per garantire che tutti i dati di ricerca precedenti vengano cancellati.

Recuperare l’elenco delle applicazioni con l’API di Kinsta

Come per i siti, userete l’endpoint /applications, passerete una query contenente l’ID dell’azienda e userete il metodo find() per cercare nell’array restituito:

const CheckApplications = async (name) => {
  setName('');
  setStatus('');
  setError('');
  const query = new URLSearchParams({
  	company: `${process.env.REACT_APP_KINSTA_COMPANY_ID}`,
  }).toString();
  const resp = await fetch(
  	`${KinstaAPIUrl}/applications?${query}`,
  	{
      	method: 'GET',
      	headers: {
          	Authorization: `Bearer ${process.env.REACT_APP_KINSTA_API_KEY}`
      	}
  	}
  );
  const data = await resp.json();
  let appsData = data.company.apps.items;
  let app = appsData.find(app => app.unique_name === name || app.name === name || app.display_name === name);
  if (app) {
  	setName(app.display_name);
  	if (app.status === 'deploymentSuccess') {
      	setStatus('🟢 Running');
  	} else if (app.status === 'deploymentFailed') {
      	setStatus('🔴 Failed');
  	} else if (app.status === 'deploymentPending') {
      	setStatus('🟡 Pending');
  	} else if (app.status === 'deploymentInProgress') {
      	setStatus('🟡 In Progress');
  	} else {
      	setStatus('🟡 Unknown');
  	}
  	setUniqueName('');
  } else {
  	setError('No such app found for your account');
  	setUniqueName('');
  }
}

Recuperare un elenco di database con l’API di Kinsta

Per recuperare un elenco di database, usate l’endpoint /databases dell’API di Kinsta:

const CheckDatabases = async (name) => {
  setName('');
  setStatus('');
  setError('');
  const query = new URLSearchParams({
  	company: `${process.env.REACT_APP_KINSTA_COMPANY_ID}`,
  }).toString();
  const resp = await fetch(
  	`${KinstaAPIUrl}/databases?${query}`,
  	{
      	method: 'GET',
      	headers: {
          	Authorization: `Bearer ${process.env.REACT_APP_KINSTA_API_KEY}`
      	}
  	}
  );
  const data = await resp.json();
  let databasesData = data.company.databases.items;
  let database = databasesData.find(database => database.name === name || database.display_name === name);
  if (database) {
  	setName(database.display_name);
  	if (database.status === 'ready') {
      	setStatus('🟢 Running');
  	} else if (database.status === 'creating') {
      	setStatus('🟡 Creating');
  	} else {
      	setStatus('🟡 Unknown');
  	}
  	setUniqueName('');
  } else {
  	setError('No such database found for your account');
  	setUniqueName('');
  }
}

In questo modo avete utilizzato l’API di Kinsta nel vostro progetto React. Per assicurarvi che la vostra applicazione funzioni bene, aggiungete al vostro markup i dati restituiti da queste funzioni, impostati sugli stati creati in precedenza:

{status !== '' && (
  <div className="services">
  	<div className="details">
      	<div className="name-details">
          	<span> className="tag">Name: </span>
          	<span> className="value">{name}</span>
      	</div>
      	<div className="status-details">
          	<span> className="tag">Status: </span>
          	<span> className="value"> {status}</span>
      	</div>
  	</div>
  </div>
)}

Aggiungete una condizione che verrà attivata in caso di errore. Per esempio, quando un utente cerca un progetto che non esiste in MyKinsta.

{error !== '' && (
  <div className="services">
  	<div className="details">
      	<p>{error}</p>
  	</div>
  </div>
)}

A questo punto il vostro progetto funzionerà correttamente e potrete controllare lo stato delle applicazioni, dei siti o dei database disponibili nel cruscotto di MyKinsta. Potete fare un controllo incrociato del vostro codice con questo repository GitHub.

Come distribuire uno status checker su Kinsta

Per distribuire un progetto React su Kinsta, è necessario inviare il progetto al proprio provider Git preferito. Se il vostro progetto è ospitato su GitHub, GitLab o Bitbucket, potete procedere al deploy su Kinsta.

Seguite questi passaggi per distribuire il vostro repository su Kinsta:

  1. Accedete o create il vostro account Kinsta nel cruscotto MyKinsta.
  2. Nella barra laterale di sinistra, fate clic su “Applicazioni” e poi su “Aggiungi servizio”.
  3. Selezionate “Applicazione” dal menu a tendina per distribuire un’applicazione React su Kinsta.
  4. Nella finestra di dialogo che appare, scegliete il repository che volete distribuire. Se avete più branch, potete selezionare quello che desiderate e dare un nome alla vostra applicazione.
  5. Selezionate uno dei data center disponibili dall’elenco dei 25 disponibili. Kinsta rileverà automaticamente il comando di avvio dell’applicazione.

Infine, ricordate che non è sicuro inviare le chiavi API a host pubblici come il vostro provider Git. Durante l’hosting, potete aggiungerle come variabili d’ambiente utilizzando lo stesso nome e valore della variabile specificata nel file .env.

Schermata di DevKinsta con le opzioni sulle variabili d’ambiente
Impostare le variabili d’ambiente su DevKinsta durante la distribuzione.

Una volta avviata la distribuzione dell’applicazione, il processo inizierà e si concluderà in genere in pochi minuti. Quando la distribuzione sarà conclusa, riceverete un link per accedere alla versione distribuita. Per esempio, in questo caso il link è https://status-checker-1t256.kinsta.app/.

Riepilogo

La chiave API di Kinsta permette di automatizzare facilmente le attività, recuperare i dati e integrare Kinsta con altre applicazioni. Ricordatevi di mantenere la vostra chiave di accesso al sicuro.

Ora potete sfruttare la potenza dell’API di Kinsta per creare report, programmare attività, creare siti WordPress e automatizzare varie attività.

Quale endpoint vi piacerebbe vedere nell’API di Kinsta? Scrivetelo nei commenti.

Joel Olawanle Kinsta

Joel è uno Frontend developer che lavora in Kinsta come redattore tecnico. È un insegnante appassionato che ama l'open source e ha scritto oltre 200 articoli tecnici principalmente su JavaScript e i suoi framework.