APIs

API (toepassingsprogramma-interface) laat klanten FMS integreren in hun systemen, en gegevens over verschillende entiteiten ophalen en doorsturen.

De client doet HTTP-verzoeken aan het systeem, waarbij informatie wordt verstrekt over de voorgenomen actie. HTTP-commando’s die gewoonlijk in een API worden gebruikt:

  • KRIJGEN – Lees bron;
  • POST– Wijzig bronstatus;

De opgevraagde inhoud wordt geleverd in JSON-formaat met UTF-8-codering. Als een ander formaat wordt gebruikt, wordt dat in de beschrijving van de methode vermeld.

HTTP-statuscode geeft de status van het verzoek aan – voor succesvolle verzoeken wordt statuscode 200geretourneerd. Samen met dit antwoord wordt de gevraagde informatie van de server ontvangen. De antwoorden zullen verschillen afhankelijk van het type API dat wordt gebruikt. De API-antwoorden voor de verschillende API-types worden in de volgende hoofdstukken beschreven.

Indien er een fout is opgetreden in het verzonden verzoek, zal het systeem een antwoordbericht terugsturen met een statuscode. Veel voorkomende foutcodes:

  • Code 400 – Slecht verzoek – API verzoek werd niet herkend.
  • Code 401 – Niet geautoriseerd – Dit betekent dat de authenticatiegegevens ontbreken of onjuist zijn;
  • Code 403 – Forbidden – Dit betekent dat de client geen recht heeft op toegang tot de gevraagde bron of het uitvoeren van de gevraagde actie;
  • Code 404– Niet gevonden – Dit betekent dat de gevraagde bron niet is gevonden.
  • Code 500 – Interne serverfout – neem contact op met de technische ondersteuning van uw provider.

Foutcodes geven enige algemene informatie over het soort fout, zodat de gebruiker de oorzaak van het probleem kan achterhalen.

Sommige API’s hebben optionele elementen (parameters) in hun respons, optionele parameters kunnen om verschillende redenen door het systeem worden overgeslagen (geen gegevens, slechte gegevens, respons time out, enz.) Een gebruiker mag er niet van uitgaan dat bepaalde facultatieve gegevens altijd in een antwoord zullen worden opgenomen.

API Beperkingen

Alle API’s hebben één enkele beperking:

  • Niet meer dan 1000 verzoeken per minuut.

Deze beperking geldt voor alle bestaande FMS API’s.

API-authenticatie

API-authenticatie en -autorisatie zijn nodig om het API-gebruik voor verschillende cliënten en hun integratie met verschillende systemen te controleren. Om een geautoriseerd verzoek te doen aan systeem-API’s, moet de verzoekende toepassing van de cliënt eerst een API-sleutelverkrijgen namens de webgebruiker van het systeem.

Cliënten kunnen alleen een API-sleutel verkrijgen door rechtstreeks contact op te nemen met de technische ondersteuning van hun dienstverleners. API sleutel bestaat uit willekeurig gegenereerde letters, cijfers en symbolen.

Voorbeeld van een verzoek waarbij een API_key wordt gebruikt:

Indien de API_key is verlopen, verwijderd of eenvoudigweg uitgeschakeld, zal het systeem de volgende reactie terugsturen:

API endpoints, verzoekparameters en antwoorden kunnen via deze link in “Swagger” worden bekeken: https://api.fm-track.com

Notitie!
Bij alle soorten API’s moet altijd een API-versie worden opgegeven.

Belangrijk!
Vanwege de voortdurende ontwikkeling van zowel de API als het systeem van waaruit de informatie wordt opgevraagd, kunnen gebruikers soms parameters ontvangen die niet in de beschrijvingen zijn opgenomen. Het wordt aanbevolen om onbekende parameters die niet gedocumenteerd zijn in de beschrijving van elke API, gewoon te negeren.

Versiebeheer en compatibiliteit

De API-oplossing wordt voortdurend bijgewerkt, verbeterd en anderszins gewijzigd, en daarom is het noodzakelijk te begrijpen wat “compatibiliteit” betekent en hoe dit de gebruiker beïnvloedt bij het gebruik van de API-oplossing.

Wanneer een API wordt bijgewerkt, gebeurt een van de volgende twee mogelijkheden:

  • De API is achterwaarts compatibel – dit betekent dat de aangebrachte wijzigingen de workflow van de API op geen enkele manier zullen beïnvloeden, er wordt dus geen nieuwe versie gecreëerd.
  • De API is niet achterwaarts compatibel – dit betekent dat sommige onderdelen van de API zodanig zijn gewijzigd dat zij niet meer op dezelfde manier werken als voorheen. In dat geval wordt een nieuwe versie van de API vrijgegeven.

Wat wordt beschouwd als een achterwaarts compatibele API-versie:

  • Nieuwe API-bron werd toegevoegd;
  • Nieuwe optionele verzoekparameters werden toegevoegd aan de bestaande API
  • Er werden nieuwe eigenschappen toegevoegd aan de bestaande API-reacties.
  • De volgorde van de eigenschappen werd gewijzigd in bestaande API antwoorden.
  • De lengte of opmaak van object ID’s of andere ondoorzichtige tekenreeksen wijzigen.
    De gebruiker kan er veilig van uitgaan dat de object ID’s die het systeem genereert nooit langer zullen zijn dan 255 tekens, maar de gebruiker moet in staat zijn ID’s met een mogelijke lengte van 255 tekens te hanteren. Bijvoorbeeld, de gebruiker gebruikt MySQL, ID’s moeten worden opgeslagen in een VARCHAR(255) COLLATE utf8_bin kolom (de COLLATE configuratie zorgt voor hoofdlettergevoeligheid bij lookups).
  • Het toevoegen van nieuwe ENUM-typen. – Elk systeem moet op een nette manier omgaan met onbekende ENUM-types. Als bijvoorbeeld het type verandert van [Privé, Zakelijk] in [Privé, Werk, Zakelijk] zou dit geen enkel effect mogen hebben voor het systeem.

 

‹   Tachograaf menu
Rijtijden menu  ›