Handleiding Aan de slag met REST API

HireHop is gebouwd op basis van een API, wat betekent dat alles wat je HireHop ziet doen, je ook kunt bereiken met behulp van de uitgebreide API. Het enige wat je nodig hebt om toegang te krijgen tot de REST API is een gebruikerstoken die wordt meegegeven als GET- of POST-parameter naar het relevante URL-eindpunt.

API-tokens

Om een API-token te genereren, ga je naar de pagina “Instellingen” en selecteer je het tabblad “Gebruikers”. Selecteer of maak een gebruiker aan, klik vervolgens terwijl die specifieke gebruiker is geselecteerd op de knop “Menu” en kies de optie “API-token” om een token te genereren. Het token wordt vervolgens weergegeven en kan naar het klembord worden gekopieerd met de kopieerknop.

Het token wordt ongeldig als je het e-mailadres of wachtwoord van de geselecteerde gebruiker wijzigt, of als je later inlogt met die gebruiker. Om te voorkomen dat dit gebeurt, moet je een speciale API-gebruiker aanmaken en deze om veiligheidsredenen de juiste rechten geven, zodat deze wordt beperkt tot functies waarvoor je de API niet gebruikt.

Om veiligheidsredenen mag je het token nooit gebruiken in front-end JavaScript-code; het mag alleen server-side worden gebruikt. Als een hacker het token bemachtigt, kan deze namelijk je gegevens in HireHop wijzigen en inzien. Bewaar je token dus goed geheim. Als je token toch lekt, wijzig dan eenvoudig het wachtwoord van de API-gebruiker en genereer een nieuw token.

Een token gebruiken

Een token moet worden ingesteld als een GET- of POST-parameter met de naam “token”. Om bijvoorbeeld projectgegevens voor projectnummer 52 te laden, roept HireHop het volgende API-eindpunt aan:

https://myhirehop.com/php_functions/job_refresh.php?job=52

Als je hetzelfde eindpunt wilt aanroepen met een token, zou de URL als volgt zijn:

https://myhirehop.com/php_functions/job_refresh.php?job=52&token=dqwejk5GVT65909bHHBN7922pq5hxjm%207hmn

Vergeet niet dat wanneer je het token via GET doorgeeft (een URL-parameter zoals hierboven), je het token eerst moet coderen met een tool zoals URL-decoder/encoder.

Gegevens versturen

Om gegevens aan te maken of te bewerken in HireHop moet je een POST gebruiken. Bij het versturen van gegevens hoef je alleen de velden in te stellen die je wilt wijzigen, bijvoorbeeld om een project aan te maken of te bewerken via het eindpunt:

https://myhirehop.com/php_functions/job_save.php

Als je de parameter “job” instelt op “0” of deze weglaat, wordt er een nieuw project aangemaakt; al het andere bewerkt het betreffende projectnummer. Om dus de bedrijfsnaam in projectnummer 52 te bewerken, moeten de post-gegevens als volgt zijn:

{
"job" : 52,
"name" : "New Name",
"token" : "dqwejk5GVT65909bHHBN7922pq5hxjm=-7hmn"
}

API-eindpunten

Veel API-eindpunten worden beschreven in de API-documentatie, en er zullen er nog vele volgen. Om het eindpunt voor een taak te achterhalen, kun je in de HireHop-applicatie de browser-netwerkconsole gebruiken om de netwerkaanroepen en ingestelde parameters te inspecteren. Binnenkort wordt er een uitgebreide handleiding voor de URL-eindpunten gepubliceerd.