Een API (Application Programming Interface) is een software-interface die het mogelijk maakt dat twee applicaties gegevens kunnen uitwisselen. Je kunt vanuit een externe applicatie data opvragen bij Colibris, of je kunt data doorsturen naar Colibris op een gestandaardiseerde manier. Op die manier kan je taken automatiseren die je normaalgezien in Colibris zelf uitvoert (bv. het automatisch aanmaken van een nieuwe lener in Colibris op het moment dat die ook wordt toegevoegd in andere software).
Wij stellen een REST API ter beschikking met CRUD acties (via de HTTP methodes GET, POST, PUT, DELETE). Het antwoord wordt steeds bezorgd in JSON-formaat.
Om vertrouwd te worden met de mogelijkheden van onze API, en om calls te testen zonder te moeten programmeren, kan je bijvoorbeeld gebruik maken van Postman.
Het vergt technische kennis en vaardigheid in programmeren om een API te gebruiken. Hoewel we voorbeeldcode ter beschikking stellen in PHP, bieden we geen uitgebreide ondersteuning voor de verdere implementatie ervan in externe systemen. Kan je niet programmeren, dan zal je helaas weinig voordeel kunnen halen uit de API.
Toegang tot de REST API is voorbehouden voor de Multi-licentie
Starten met de API
Om de API te gebruiken, heb je een API key nodig die bestaat uit drie basisgegevens. Bij elke call zal je deze gegevens moeten doorgeven in de HTTP headers. Je vindt deze gegevens onder Instellingen > REST API. Twee ervan liggen vast en zijn dus meteen zichtbaar, maar de API key zal je zelf nog moeten activeren.
- X-Api-User: de publieke klant ID zoals die ook in de URL van je Colibris omgeving zit, meer bepaald app.colibris.be/<klantID>/
- X-Api-Login: een unieke logincode, deze is onlosmakelijk verbonden met je Colibris omgeving
- X-Api-Key: een unieke sleutel, die je zelf kunt aanmaken of op eender welk moment kunt wijzigen door op ‘Genereer een nieuwe API key’ te klikken
In de voorbeeldcode onderaan vervang je API_USER, API_LOGIN en API_KEY door de gegevens die je vindt in je instellingen.
API toegangspunten
De API heeft momenteel deze toegangspunten. Je vermeldt het juiste toegangspunt in de parameter CURLOPT_URL
Leners beheren
- GET /users
Volledige lijst met leners opvragen - GET /users/{id}
Gegevens van een specifieke lener opvragen - POST /users
Nieuwe lener aanmaken - POST /users/{id}
Bestaande lener aanpassen - DELETE /users/{id}
Bestaande lener verwijderen
Uitleen
- GET /loans/{id}
Uitleenoverzicht opvragen van een lener
Collectie
- GET /catalog
Gegevens opvragen van een specifiek item / Lijst met recente aanwinsten opvragen
API Voorbeeldcode in PHP
De voorbeeldcode doet op zich niets, maar verduidelijkt het basisprincipe en laat je vooral toe om de connectie te testen. Meer concrete voorbeeldcode (inclusief een voorbeeldantwoord) vind je in de specifieke helpartikels over de verschillende toegangspunten.
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.colibris.be/users",
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => array(
'X-Api-User: API_USER',
'X-Api-Login: API_LOGIN',
'X-Api-Key: API_KEY',
'Content-Type: application/json'
),
));
$data = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "Error #:" . $err;
} else {
print_r($data);
}
?>API beperkingen
Toegang tot de API is beperkt tot 20 requests per minuut. Wanneer je over deze limiet gaat, zal er een time-out van 1 minuut zijn.
De API is dus erg geschikt om ‘druppelsgewijs’ data uit te wisselen. Wanneer je ineens honderden leners wil importeren, dan is de Excel import beter geschikt.