Kinsta is een cloudplatform dat is ontworpen om bedrijven en devteams te helpen bij het sneller en efficiënter shippen en beheren van hun webprojecten.

Kinsta biedt ontwikkelaars en gebruikers een API om hun WordPress sites, applicaties en databases programmatisch te beheren.

De Kinsta API kan worden gebruikt om taken te automatiseren, data op te halen en Kinsta te integreren met andere applicaties zonder dat toegang tot MyKinsta nodig is. Om toegang te krijgen tot de API heb je een API sleutel nodig. Dit artikel legt het proces uit van het maken en gebruiken van een Kinsta API sleutel.

Zo maak je een API sleutel aan

Om Kinsta’s API te gebruiken, moet je een account hebben met ten minste één WordPress site, applicatie of database in MyKinsta. Je moet ook een API sleutel genereren om je te authenticeren en toegang te krijgen tot je account via de API. Om een API sleutel te genereren:

  1. Ga naar je MyKinsta dashboard.
  2. Navigeer naar de pagina API sleutels (Je naam > Bedrijfsinstellingen > API sleutels).
  3. Klik op Maak API sleutel aan.
  4. Kies een vervaldatum of stel een aangepaste begindatum in en het aantal uren dat de sleutel moet verlopen.
  5. Geef de sleutel een unieke naam.
  6. Klik op Genereer.
API sleutel aanmaken op MyKinsta.
API sleutel aanmaken op MyKinsta.

Wanneer je een API sleutel aanmaakt, kopieer deze dan en bewaar hem ergens veilig, want dit is de enige keer dat je hem kunt zien. Je kunt meerdere API sleutels aanmaken – ze worden weergegeven op de pagina API sleutels. Als je een API sleutel wilt intrekken, klik je op Intrekken naast de sleutel die je wilt intrekken.

Zo gebruik je Kinsta API gebruiken met je API sleutel

Zodra je de API-sleutel hebt, kun je communiceren met alle diensten van Kinsta (WordPress sites, Applicaties en Databases) via de Kinsta API, zoals het opvragen van een lijst met databases op bedrijfs-ID, bedrijfssites, het maken van een WordPress site en meer.

Om bijvoorbeeld een lijst met bedrijfssites in je MyKinsta op te vragen, is het endpoint /sites. De API sleutel zal dienen als je autorisatieheader; je voegt ook de bedrijfs-ID toe (verplichte parameter). Hier zie je hoe je dit API verzoek doet met cURL:

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

Vervang YOUR_API_KEY_HERE door de werkelijke API sleutel die je hebt gegenereerd en

COMPANY_ID_HERE met je unieke bedrijfs-ID. Dit geeft een JSON respons van alle bedrijfssites in je DevKinsta dashboard:

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

Een ander voorbeeld, stel dat je een specifieke site wilt ophalen op ID (GET-verzoek). Je kunt het /sites/{site_id} endpoint gebruiken. {site_id} zal worden vervangen door het unieke ID van de specifieke site die je wilt ophalen. Hier zie je hoe je dit API verzoek doet met 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();

Er is meer mogelijk met de Kinsta API. Voor volledige details over beschikbare API endpoints en de benodigde parameters, om onze OpenAPI specificatie te downloaden en endpoints uit te proberen, zie je onze API Reference.

Rechten

API toegangsrechten voor Kinsta zijn afhankelijk van de rol van de gebruiker binnen het bedrijf, aangezien Company Owners, Company Administrators en Company Developers API sleutels kunnen aanmaken.

Een API sleutel die is gegenereerd door een Developer heeft bijvoorbeeld niet hetzelfde toegangsniveau als een sleutel die is gegenereerd door een Owner of Administrator. De specifieke rechten die bij elke gebruikersrol horen zorgen voor de juiste toegangscontrole en beveiliging voor de Kinsta API.

Zo gebruik je de Kinsta API om een statuschecker te bouwen

Wanneer je een applicatie, site of database maakt op MyKinsta, doorloopt deze verschillende stadia. Een manier om deze stadia te identificeren is door middel van hun status. Een applicatie die wordt gedeployd op Kinsta heeft een bijvoorbeeld status voor wanneer deze wordt gedeployd, succesvol is gedeployd of is mislukt.

De Kinsta API biedt endpoints waarmee je statusinformatie kunt ophalen over je projecten op MyKinsta. Voor dit project zul je communiceren met drie endpoints, namelijk de /applications, /sites, en /databasesom een array van alle applicaties, sites en databases op te halen met behulp van de JavaScript Fetch API.

Zodra je de lijst hebt opgehaald, kun je de methode find() in JavaScript gebruiken om te zoeken naar een specifieke projectnaam die is ingevoerd in de gebruikersinterface (UI). Dit geeft de naam en status van het project als het bestaat.

Statuschecker webapplicatie.
Statuschecker webapplicatie.

Vereisten

Om dit project te kunnen volgen, is het raadzaam om een basiskennis te hebben van HTML, CSS en JavaScript en enige bekendheid met React. De belangrijkste focus van dit project is het demonstreren van het gebruik van de Kinsta API, dus het artikel gaat niet in op de details van het maken van UI of styling.

Je kunt een Git repository maken met deze template op GitHub. Selecteer Use this template > Create a new repository om de startcode te kopiëren naar een nieuwe repository binnen je eigen GitHub account, en zorg ervoor dat je het vakje om alle branches mee te nemen aanvinkt. Als je naar je lokale computer gaat, zorg er dan voor dat je overschakelt naar de status-checker-ui branch om de startbestanden te gebruiken met het onderstaande commando:

git checkout status-checker-ui

Installeer de benodigde dependencies door het commando npm install uit te voeren. Als de installatie voltooid is, kun je het project op je lokale computer starten met het commando npm run start. Dit zal het project openen op http://localhost:3000/.

Controleer de status van MyKinsta projecten.
Controleer de status van MyKinsta projecten.

Dit project heeft twee hoofdpagina’s: de Home en Service pagina’s. De Home pagina toont een lijst met diensten die worden geleverd door Kinsta (WordPress-, applicatie- en databasehosting). Als je op een van de diensten klikt, kom je op de Service pagina, die is ontworpen om specifieke informatie te geven over de geselecteerde dienst.

Als je bijvoorbeeld op de sectie “Applications” klikt, word je doorgestuurd naar de Service pagina voor applicaties. Je kunt op deze pagina zoeken naar elke applicatie binnen je MyKinsta account, zodat de status van de applicatie wordt opgehaald aan de hand van de unieke naam of de weergavenaam.

Interactie met de Kinsta API

Om de zoekfunctie voor dit project te benutten, maak je drie functies om de ophaalverzoeken voor elke service (applicaties, sites en databases) af te handelen. Vervolgens implementeer je een zoekfunctie die de hele reeks gegevens scant om te controleren of een bepaalde zoekwaarde bestaat.

Je hebt je bedrijfs-ID en API sleutel nodig voor interactie met de Kinsta API, zodat je een lijst kunt ophalen van databases, applicaties en sites die beschikbaar zijn in je MyKinsta account. Als je ze eenmaal hebt, sla ze dan op als omgevingsvariabelen in je React applicatie door een .env bestand aan te maken in de hoofdmap van je project.

REACT_APP_KINSTA_COMPANY_ID = 'YOUR_COMPANY_ID'
REACT_APP_KINSTA_API_KEY = 'YOUR_API_KEY'

Je hebt nu overal in je project toegang tot deze waarden met process.env.THE_VARIABLE. Om bijvoorbeeld toegang te krijgen tot REACT_APP_KINSTA_COMPANY_ID, gebruik je process.env.REACT_APP_KINSTA_COMPANY_ID.

Voordat je de API gebruikt, maak je drie states aan in de Service.jsx pagina om de state en naam op te slaan van de uitvoer die gegenereerd wordt als je zoekt naar een site, applicatie of database. De derde state is om foutinformatie op te slaan.

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

Maak ook een variabele om de Kinsta API URL op te slaan:

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

Als je klaar bent, koppel dan een onClick event aan een CheckQuery() functie aan de verzendknop van het formulier op de Service.jsx pagina, zodat deze een functie triggert op basis van de slug. Dus als de slug databases aangeeft, wordt de CheckDatabases() functie geactiveerd:

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);
  }
}

Lijst met sites ophalen met Kinsta API

Om een lijst van sites op te halen die beschikbaar zijn op je MyKinsta bedrijfsaccount met Kinsta API, maak je een functie, geef je een query door met de bedrijfs-ID als parameter en autoriseer je het verzoek met je API sleutel. Dit verzoek zal het /sites endpoint van de Kinsta API gebruiken:

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}`
          }
      }
  );
}

Deze bovenstaande code zal alle sites ophalen die beschikbaar zijn in je MyKinsta account, je kunt nu de methode find() gebruiken om te zoeken als de zoekopdracht overeenkomt met een naam of weergavenaam:

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

Hiermee kun je vervolgens enkele voorwaarden maken om te controleren of het een waarde oplevert, stel dan de states in en werk anders de foutstatus bij met een bericht om de gebruiker te informeren dat een dergelijke site niet bestaat:

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('');
}

Als je dit allemaal samenvoegt, ziet je code om de status van een bepaalde site te controleren er zo uit:

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('');
  }
}

Opmerking: Alle drie de states worden geïnitialiseerd als lege strings telkens wanneer de functie CheckSites() wordt geactiveerd. Dit is nodig om ervoor te zorgen dat alle eerdere zoekgegevens worden gewist.

Lijst met applicaties ophalen met Kinsta API

Net zoals je deed voor sites, gebruik je het /applications endpoint, geef je een query door die de ID van het bedrijf bevat en gebruik je ook de find() methode om de geretourneerde array te doorzoeken:

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('');
  }
}

Lijst van databases ophalen met Kinsta API

Om een lijst met databases op te halen, gebruik je het /databases endpoint van de Kinsta API:

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('');
  }
}

Zodra dit is gedaan heb je de Kinsta API met succes gebruikt in je React project. Om ervoor te zorgen dat je app goed werkt, voeg je de gegevens die worden geretourneerd uit deze functies, die zijn ingesteld op de states die we eerder hebben gemaakt, toe aan je markup code:

{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>
)}

Voeg ook een voorwaarde toe die wordt geactiveerd als er een fout optreedt. Als een gebruiker bijvoorbeeld zoekt naar een project dat niet bestaat in MyKinsta, wordt de fout geactiveerd.

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

Op dit punt werkt je project goed en kun je de status van applicaties, sites of databases controleren die beschikbaar zijn op je MyKinsta dashboard. Je kunt je code controleren met deze GitHub repository.

Hoe je je statuschecker kunt deployen op Kinsta

Om je React project uit te rollen naar Kinsta, moet je het project pushen naar de Git provider van je voorkeur. Als je project wordt gehost op GitHub, GitLab of Bitbucket, kun je het deployen naar Kinsta.

Om je repository naar Kinsta te deployen, volg je deze stappen:

  1. Log in of maak je Kinsta account aan op het MyKinsta dashboard.
  2. Klik in de linker zijbalk op “Applicaties” en vervolgens op “Dienst toevoegen”.
  3. Selecteer “Applicatie” in het vervolgkeuzemenu om een React applicatie te deployen op Kinsta.
  4. Kies in het venster dat verschijnt de repository die je wilt deployen. Als je meerdere branches hebt, kun je de gewenste branch selecteren en een naam geven aan je applicatie.
  5. Selecteer een van de beschikbare datacenterlocaties uit de lijst van 25 opties. Kinsta zal automatisch het start-commando voor je applicatie detecteren.

Tot slot is het niet veilig om API sleutels naar publieke hosts zoals je Git provider te pushen. Bij het hosten kun je ze toevoegen als omgevingsvariabelen met dezelfde variabelennaam en waarde die zijn opgegeven in het .env bestand.

Controleer de status van MyKinsta projecten bij het deployen.
Stel omgevingsvariabelen in op DevKinsta bij het deployen.

Zodra je de deployment van je applicatie start, zal het proces beginnen en meestal binnen een paar minuten voltooid zijn. Je ontvangt een link om toegang te krijgen tot de uitgerolde versie van je applicatie als de deployment is geslaagd. In dit geval is de link bijvoorbeeld https://status-checker-1t256.kinsta.app/.

Samenvatting

Met de Kinsta API sleutel kun je eenvoudig taken automatiseren, gegevens ophalen en Kinsta integreren met andere applicaties. Vergeet niet om je toegangssleutel veilig te bewaren.

Nu kun je de kracht van de Kinsta API gebruiken om bepaalde rapportages te maken, taken te plannen, WordPress sites te maken en verschillende activiteiten te automatiseren.

Welk endpoint zou jij graag toegevoegd zien aan de Kinsta API? Laat het ons weten in de comments.

Joel Olawanle Kinsta

Joel is a Frontend developer working at Kinsta as a Technical Editor. He is a passionate teacher with love for open source and has written over 300 technical articles majorly around JavaScript and it's frameworks.