De voortdurende doorontwikkeling van vPlan brengt ook veranderingen in de API met zich mee. De afgelopen periode zijn verbeteringen doorgevoerd die de snelheid van integraties en API gebruik ten goede komen.
Per 1 oktober 2022 is het gebruik van paginering vanaf 1000 records verplicht.
In dit artikel lees je meer over verplichte paginering, maar ook andere belangrijke best practices om je API integratie zo efficiënt en snel mogelijk te laten werken.
Verplichte paginering
Beschikbaarheid van 'with' parameter
Afslanken van de reactie
Waarschuwing verouderde aanroepen
Verplichte paginering
Tot op heden hebben we paginering sterk aangeraden maar nooit verplicht. Per 1 oktober 2022 is dit veranderd. Zie onderstaande scenario's hoe vPlan API de limits afhandelt en of een aanpassing van jouw integratie nodig is.
- limit tussen 1 en 1000
Gevolg: Geen actie nodig. - limit groter dan 1000
Gevolg: De API geeft een foutmelding in plaats van een resultaat. Pas de paginering aan zodat deze binnen onze limiet valt. - limit met 0
Gevolg: De API geeft een foutmelding in plaats van een resultaat. Pas de paginering aan zodat deze binnen onze limiet valt. - Geen limit opgegeven
Gevolg: De limiet wordt standaard op 100 ingesteld. Hierdoor kunnen potentieel gegevens ontbreken in je API request. Controleer of dit nu of in de toekomst problemen kan geven, wel is ons dringende advies om paginering toe te passen.
Beschikbaarheid van 'with' parameter
Zoals bekend biedt onze API de optie om gerelateerde data bij een object in 1 request op te halen. Tot op heden heeft vPlan de parameter include beschikbaar gesteld. Sinds geruime tijd hebben we hiervoor een vervangende parameter with beschikbaar gesteld. Net zoals bij include geeft with de mogelijkheid om gerelateerde data bij een object in 1 keer op te halen.
Het voordeel van with is dat deze bijna 2 keer zo snel is!
De mogelijke opties voor with zijn per object beschreven in onze API documentatie.
Afslanken van de reactie
In het kader van 'less is more' hebben wij recentelijk de optie toegevoegd om het resultaat van onze API af te slanken. Door middel van de show en hide parameters kun je aangeven welke velden je specifiek wel of juist niet wilt ontvangen.
Het gebruik van deze parameters geeft 2 grote voordelen:
- Beperken van de hoeveelheid data die over de lijn gaat
- Voorspelbaarheid van de te ontvangen data
Als jouw integratie strikte verwachtingen heeft m.b.t. de te ontvangen data, kun je via de show ervoor zorgen dat niet onverwachts velden toegevoegd worden. Bijvoorbeeld wanneer door vPlan velden worden toegevoegd voor nieuwe features.
Deze parameters zijn niet alleen bij het ophalen van data te gebruiken, maar zijn daarnaast bruikbaar voor het aanmaken van object. Op deze manier zou je bijvoorbeeld alleen het id veld kunnen opvragen voor een nieuw object.
Waarschuwing verouderde aanroepen
De ontwikkeling van de API loopt mee met de ontwikkelingen in vPlan. Hierdoor ontstaat de kans dat features aangepast of uitgefaseerd worden. In dit geval voegt vPlan waar mogelijk een depracated header toe aan de response. Wij begrijpen dat deze header lang niet altijd opgepakt wordt door een client. Daarom bieden we ook een endpoint (v1/api_message) aan waarbij mogelijk vroegtijdige waarschuwingen opgehaald kunnen worden.
In geval van de aanpassing van de limit is het belangrijk om te kijken naar de volgende codes:
- RESULT_GT_100 -> geen limit opgegeven, en resultaat is groter dan 100
- LIMIT_EQ_0 -> limit van 0 opgegeven
- LIMIT_GT_1000 -> limit groter dan 1000 opgegeven