In deze handleiding laten wij zien hoe je in PHP automatische authenticatie met de TransIP REST API inricht. Schakel voor je aan dit artikel begint alvast de API in en genereer een Key Pair. Hoe dit werkt leggen wij in deze tutorial uit.

Vereisten

Voor het gebruik van de REST API PHP-Library moet de volgende software op je server geïnstalleerd zijn:

• PHP 7.2 of nieuwer
• PHP-json
• OpenSSL
• Composer

PHP

Voor de installatie van PHP kun je gebruik maken van onze handleidingen voor de installatie van Apache met PHP-ondersteuning. Het is niet nodig Apache te installeren als je geen website wil hosten. Je hoeft voor PHP dan ook enkel het deel van de handleiding te gebruiken dat over PHP gaat.

PHP-json + OpenSSL

De PHP-json extensie en OpenSSL installeer je afhankelijk van je besturingssysteem met:

CentOS:

sudo yum -y install php-json openssl

Ubuntu/Debian:

sudo apt -y install php-json openssl

Composer

Composer is een tool voor dependency management in PHP. Je kunt met Composer eenvoudig aangeven welke libraries je project nodig heeft (de dependencies) en Composer beheert deze vervolgens voor je. Voor de installatie van Composer kun je deze handleiding gebruiken.

Automatische authenticatie

In de stappen hieronder laten wij zien hoe je automatisch de authenticatie met de TransIP REST API via PHP verzorgt.

Stap 1

Verbind met je server via command-line/RDP.

Stap 2

Navigeer naar je project-directory op je VPS, stel dat je de API wil gebruiken op je website example.com, dan kan dit bijvoorbeeld zijn:

cd /var/www/html/example.com/

Stap 3

Om Composer te kunnen gebruiken moet er in de projectdirectorie een bestand genaamd composer.json met daarin de require key aanwezig zijn. De require key vertelt composer welke packages je project nodig heeft.

Nieuw composer project

Start je een nieuw project en begin je daarin net met composer, dan zal composer.json nog niet aanwezig zijn. Maak dit bestand aan met:

touch composer.json
echo '{' > composer.json
echo '   "require": '{ >> composer.json
echo '   }' >> composer.json
echo '}' >> composer.json

Krijg je een melding dat je het bestand niet kunt aanmaken? Controleer dan of je gebruiker de juiste rechten heeft om bestanden te maken en bewerken in de map waar je in werkt.

Ga vervolgens door naar stap 4.

Bestaand composer project

Is je project al geïnitialiseerd? Voeg dan enkel de REST API als requirement toe met het commando hieronder en ga dan door naar Stap 5:

composer require transip/transip-api-php

Stap 4

Initieer het project in Composer met het commando:

composer init

Je krijgt nu een aantal vragen op basis waarvan een configuratiebestand genaamd composer.json wordt gegenereerd. Hieronder vind je een voorbeeld van deze stappen met daaronder een toelichting van ieder item.

This command will guide you through creating your composer.json config.

Package name (<vendor>/<name>) [transip/html]:
Description []: transip API demo
Author [, n to skip]: n
Minimum Stability []:
Package Type (e.g. library, project, metapackage, composer-plugin) []:
License []: 

Define your dependencies.

Would you like to define your dependencies (require) interactively [yes]? yes
Search for a package: transip/transip-api-php
Enter the version constraint to require (or leave blank to use the latest version): ^6.0
Search for a package: 
Would you like to define your dev dependencies (require-dev) interactively [yes]? no

{
    "name": "transip/html",
    "description": "transip demo",
    "require": {
        "transip/transip-api-php": "^6.0"
    }
}
Do you confirm generation [yes]? yes
Would you like to install dependencies now [yes]? yes

Toelichting

• Package name: Wordt standaard ingevuld en hoef je niet aan te passen.
• Description: Geef het project een herkenbare naam.
• Author: Deze stap is optioneel, druk op 'n' om hem op te slaan of geef je naam en e-mailadres op.
• Minimum stability: Laat deze optie leeg en druk op 'Enter'. Deze optie definieert het filteren van packages op basis van stabiliteit en staat standaard enkel 'stable' releases toe.
• Package type: Laat deze optie ook leeg en druk op 'Enter'. Heeft een package extra logica nodig, bijvoorbeeld in de vorm van een plugin of extensie, dan kun je die hier opgeven. Voor onze API is dat echter niet nodig.
• License: Voeg optioneel een licentie toe waar gebruikers van je project zich aan moeten houden, bijvoorbeeld 'MIT' en druk op 'Enter' (dit is de MIT-licentie voor opensourcesoftware).
• Define dependencies interactively interactively: Vul 'Yes' in.
• Search for package: Geef de locatie van onze REST API op, oftewel transip/transip-api-php
• Enter the version constraint: De waarde ^6.0 vertelt dat versie 6.0 of nieuwer gebruikt moet worden.
• Search for package: Je kan meer packages opgeven indien gewenst. Vul niets in en druk op 'Enter' om deze keer de stap over te slaan.
• Define dev dependencies interactively: Vul deze keer 'No' in.
• Confirm the generation: Als de getoonde gegevens kloppen, type dan 'Yes' en druk op 'Enter'.

Stap 5

Verwerk de wijzigingen en update composer met het commando:

composer update

De output ziet er ongeveer als volgt uit:

In plaats van 'dev-master' zal hier bij transip/restapi-php-library v6.0.0 of nieuwer staan.

Stap 6

Maak een bestand aan die je gebruikt om de verbinding met de API te maken, bijvoorbeeld:

nano Authenticate.php

Geef het bestand de inhoud hieronder:

<?php

use \Transip\Api\Library\TransipAPI;

require_once(__DIR__ . '/vendor/autoload.php');

// Your login name on the TransIP website.
$login = 'youraccountname';

// If the generated token should only be usable by whitelisted IP addresses in your Controlpanel
$generateWhitelistOnlyTokens = true;

// One of your private keys; these can be requested via your Controlpanel
$privateKey = '';

$api = new TransipAPI(
       $login,
       $privateKey,
       $generateWhitelistOnlyTokens
);

// Set all generated tokens to read only mode (optional)
$api->setReadOnlyMode(false);

// Create a test connection to the api
$response = $api->test()->test();

if ($response === true) {
   echo 'API connection successful!';
}

• Vul achter $login je TransIP-accountnaam in, bijvoorbeeld $login = 'transip';
• Vul achter $privateKey de waarde van je private key in uit stap 1 van dit onderdeel, bijvoorbeeld:

  $privateKey = '-----BEGIN PRIVATE KEY-----MIIEvgIBADANBgkqhkietcetcetcetc-----END PRIVATE KEY-----

• $api->setReadOnlyMode(false); Met read-only kun je enkel data ophalen, zoals een lijst van VPS'en of domeinen, maar geen bewerkingen uitvoeren zoals het bestellen of opzeggen van een VPS of domein. Wil je de tokens in read only made aanmaken, pas dan 'false' aan naar 'true'.

Sluit het bestand en geef toestemming de wijzigingen op te slaan (ctrl + x > y > enter).

Stap 7

Je kunt nu direct de API-verbinding testen met het commando:

php Authenticate.php

Je krijgt de volgende output te zien:

API connection succesful!

Gefeliciteerd! Je hebt nu een werkende verbinding met de API. Krijg je een foutmelding? Dit kan een van de volgende oorzaken hebben:

• Er wordt een ander IPv6-adres gebruikt dan je hebt gewhitelist en je krijgt een melding 'Remote IP is not authorized for this request; called from IP <defaultrouteadres> in ...'.
  Je kunt dit oplossen door het gebruikte IPv6-adres te whitelisten voor de API.
• Een hick up in Composer. Door opnieuw de stappen hierboven te doorlopen sluit je dit uit.

Je kunt nu het stukje code dat bedoelt is om de verbinding te testen uit Authenticate.php verwijderen, of uitcommentariëren, oftewel:

// Create a test connection to the api 
// $response = $api->test()->test();

// if ($response === true) {
//     echo 'API connection successful!'; 
// }

Authenticate.php gebruiken

In de stappen hierboven heb je het bestand Authenticate.php aangemaakt. Hierin is de functie $api gedefinieerd, waarmee je een verbinding maakt met de TransIP REST API.

Je kunt nu eenvoudig in andere PHP-files de API aanspreken door hierin de volgende regel toe te voegen:

require_once(__DIR__ . '/Authenticate.php');

__DIR__ vult in PHP automatisch de map in van waaruit het script wordt uitgevoerd. Stel dat je een .PHP-bestand aanmaakt in /var/www/html/example.com, dan wordt /var/www/html/example.com ingevuld als waarde voor __DIR__ en wordt de regel gelezen als: require_once(/var/www/html/example.com/Authenticate.php);

Gebruik je een subdirectory, bijvoorbeeld /var/www/html/example.com/voorbeeld/ waar je PHP-script in staat, dan pas je de regel aan naar:

require_once(__DIR__ . '/../Authenticate.php');

Vervolgens zet je een verbinding op door de $api functie aan te roepen, bijvoorbeeld $api->vps()->getAll(). Hoe dit werkt laten wij zijn aan de hand van enkele voorbeelden in ons artikel met REST API PHP-voorbeelden.

De namen van functies en entiteiten achterhalen

Voor het ontwikkelen van je applicatie raden wij aan een IDE te gebruiken, zodat je eenvoudiger de namen van functies e.d. kunt achterhalen.

Gebruik je geen IDE en ben je bijvoorbeeld op zoek naar de naam van een functie om een repository (e.g. vpsBackups of domainDns) aan te spreken? Kijk dan in de 'src/Transip/Api/Library/TransipAPI.php'. Hier vind je de namen van de beschikbare repositories (e.g. domainDns). Kijk daarna in de 'src/Transip/Api/Library/Repository' map voor de naam van de specifieke functie die je wilt gebruiken (e.g. getByDomainName).

Daarmee zijn we aan het eind gekomen van deze handleiding voor het opzetten van automatische authenticatie met de TransIP Rest API via PHP. Voor voorbeelden van het gebruik van de PHP-library, kun je de voorbeelden in de 'examples'-map gebruiken, of deze handleiding raadplegen.

Mocht je aan de hand van deze handleiding nog vragen hebben, aarzel dan niet om onze supportafdeling te benaderen. Je kunt hen bereiken via de knop 'Neem contact op' onderaan deze pagina.