Overgang APIv2 naar APIv3


Actie vereist - APIv1 en APIv2 zullen per 1 februari 2019 niet meer beschikbaar zijn.


Gripp heeft een nieuwe versie van de API gelanceerd. Hierin zijn een aantal veranderingen doorgevoerd, welke van invloed kunnen zijn op jouw API-script. Lees deze pagina goed door, en maak waar nodig aanpassingen in je oude APIv1 of APIv2 scripts. APIv1 en APIv2 zullen per 1 februari 2019 niet meer beschikbaar zijn.
Mocht je nog gebruik maken van de APIv1, dan raden we je aan eerst onze instructies door te nemen hoe je van APIv1 naar APIv2 kunt migreren.

Nieuwe API-connector (PhP)

Voor APIv3 is een nieuwe API-connector ontwikkeld. Deze API-connector houdt o.a. rekening met de throttling (zie verderop), en biedt een betere foutafhandeling. Je kunt de nieuwe API-connector hieronder downloaden.

Download de Gripp APIv3-connector (PhP)

API Endpoint gewijzigd

De URL waarop je verbinding maakt met je API is veranderd. Vanaf nu kun je verbinding maken via de volgende URL:

https://api.gripp.com/public/api3.php

Aantal requests per uur gelimiteerd & API Request Packs

Het gebruik van de API is explosief gegroeid de afgelopen tijd. Om de verwerking van de API-calls in goede banen te kunnen leiden, heeft Gripp flink geïnvesteerd in extra servers en monitoring. Helaas zit daar een kostenplaatje aan. Om die reden vraagt Gripp voor het gebruik van de API sinds 1 februari 2019 een kleine vergoeding. We doen dat in de vorm van API Request Packs. Om gebruik te kunnen (blijven) maken van de API, heb je één of meerdere API Request Packs nodig. Elke API request pack is goed voor 1000 requests per uur. Meer informatie over het upgraden van API Request Packs vind je op onze aparte supportpagina.

Elke response op een API-request bevat altijd de volgende headers:

  • X-RateLimit-Limit: het maximale aantal request per uur
  • X-RateLimit-Remaining: het aantal overgebleven requests voor dit uur
Wanneer je je limiet bereikt hebt, sturen we je een STATUS 429. Je zult dan moeten wachten tot het nieuwe uur, of het aantal API Request Packs moeten upgraden. Wanneer je gebruik maakt van onze API Connector, dan zal deze een Exception gooien.

Hieronder staan een aantal tips om het aantal requests zo laag mogelijk te houden:
  • Beperk de aanroep van het script: Het periodiek aanroepen van jouw API-script kan zorgen voor een hoop API calls. Wellicht kun je het eens per uur aanroepen, en niet elke 5 minuten.
  • Vermijd loops: API-calls uitvoeren in een loop zorgt voor een hoop calls, dataverkeer, en is ook nog eens tijdrovend. Vaak is het te voorkomen door buiten een loop wat meer data op te halen (bijvoorbeeld met de IN-operator).
  • Zorg voor een lokale caching: Wanneer je bijvoorbeeld relatiegegevens nodig hebt, dan is de kans groot dat deze niet elk uur worden gewijzigd. Wijzig je script dusdanig dat je bijvoorbeeld een subset van de klanten ophaalt.

Throttling

Om de overlast van API-scripts voor andere klanten te minimaliseren, worden API-calls vanaf APIv3 ge-throttled. Dit houdt in dat de verwerking van het aantal API-calls per seconde beperkt wordt. Wanneer je gebruik maakt van onze nieuwe API-connector, dan wordt hier automatisch rekening mee gehouden. Mocht je geen gebruik willen of kunnen maken van de nieuwe API-connector, dan dien je zelf te zorgen voor een correcte afhandeling van de fouten. Wanneer je API-request niet verwerkt kan worden doordat je tegen de throttling-limiet aanloopt, dan sturen we je een STATUS 503, met daarbij de volgende header:

Retry-After: 0.53
Dit betekent dat je 0.53 seconde dient te wachten voordat je API call opnieuw kunt uitvoeren. Wanneer je gebruik maakt van onze API Connector, dan zal deze de benodigde tijd wachten, alvorens de request opnieuw te doen.

Autorisatie

De API-token dient vanaf nu met een header meegegeven te worden. De HTTP header luidt als volgt:

Authorization: Bearer {YOURAPITOKEN}
Bijvoorbeeld:

Authorization: Bearer Bacg7E5bNyqy9TGiSoB1b4IlUIaKhz
Wanneer je gebruik maakt van onze nieuwe API-connector, dan wordt hier automatisch rekening mee gehouden.

API-documentatie

De officiële API-documentatie is te vinden via de link https://api.gripp.com/public/api3.php. Hier is tevens een playground beschikbaar om API calls te testen.

Technische ondersteuning

Onze supportdesk kan je helaas niet helpen bij het beantwoorden van technische of inhoudelijke vragen over je API-script. Onze technische consultants kunnen dat wel. Voor consultancy of hulp bij de ontwikkeling van een koppeling kan contact worden opgenomen met onze sales-afdeling via sales@gripp.com. Een Gripp Expert zal dan inventariseren wat de wensen zijn. (Telefonische) consultancy of werkzaamheden die betrekking hebben op een API-scripts zullen op basis van nacalculatie worden doorbelast.