Maak klanten, projecten of medewerkers aan in ClockWise vanuit andere software systemen. Zo hoeft u gegevens maar op één plek bij te houden.
Met de ClockWise Restful API kunt u gegevens in ClockWise aanmaken, updaten en verwijderen. Dezelfde API wordt gebruikt door onze mobile clients en interne afhandeling. Eventueel maatwerk is zichtbaar in de API endpoints.
De API gebruikt OAuth token authorization, waarbij verschillende software clients kunnen worden herkend. Per gebruiker kunnen eventueel tokens worden ingetrokken.
Er is een uitgebreide documentatie beschikbaar in uw ClockWise account https://omgevingsnaam.clockwise.info/api/v2/doc . Als u bent ingelogd kunt u deze benaderen.
Let op het API gebruik. In een ontwikkelproces wordt vaak pas aan het eind, of niet, gekeken naar optimalisatie. Het is eenvoudig om een koppeling op te zetten die periodiek data ophaalt en op die manier dataverkeer en server load op uw omgeving vergoot.
Aangezien veel onnodig dataverkeer en serverload niet alleen slecht is voor het milieu, maar ook gevolgen zal hebben voor de performance van uw en mogelijk andere omgevingen proberen we af te dwingen dat er slim omgegaan wordt met het gebruik van de API.
Voor het aantal requests hebben we daarom een limiet ingesteld op het aantal requests dat gedaan kan worden per gebruiker (ongeacht de gebruikte client) en voor de inhoud van de requests bij het gebruik van report endpoints die meer dan 50 resultaten per keer ophalen hebben we een limiet gesteld op het aantal records in de response en over de response grootte in bytes voor het gehele gebruik van de API (ongeacht de gebruikte client of gebruiker).
De API gebruikt een rate limiting voor het aantal requests per gebruiker van 250 calls per 15 minuten volgens de bucket methode. De bucket methode houdt in dat je in een keer 250 calls mag doen, maar dat je daarna maar 1 call per ( 15 x 60 ) / 250 = 3.6 seconden kan doen. Na 15 minuten geen gebruik van de API is de 'bucket' dan weer leeg. Bij het respecteren van deze limiet zou een normaal gebruik van requests die nodig zouden zijn voor een UI mogelijk moeten zijn.
Bij geautomatiseerde processen waar geen gebruiker aan te pas komt zouden deze rate limiting ook aangehouden moeten worden. Op deze manier neemt een geautomatiseerd proces niet meer resources dan een normale gebruiker zou nemen.
De staat van de rate limiting wordt via de response headers gecommuniceerd. Een natuurlijk gebruik die niet de rate limit overschrijdt kan worden verkregen door minimaal X-Rate-Limit-Reset/X-Rate-Limit-Limit seconden te wachten na het starten van de vorige requests, waarbij deze waarden komen ui de header van de vorige requests.
Het krijgen van een 429 response (Too Many Requests) bij overschrijden telt als een request en is niet bevorderlijk voor het totaal aantal requests dat op de API gedaan kan worden.
Via het batch call endpoint kunnen api requests gecombineerd worden. Bij de rate limiting gelden de batch requests in zijn geheel als 1 call. Bovendien verdwijnt de overhead van het doen van meerdere asynchrone calls. Batch calls zijn handig voor requests die tegelijkertijd uitgevoerd kunnen worden.
Caching zorgt ervoor dat er geen request gedaan hoeft te worden en spaart dus de rate limit van 250 API requests per 15 minuten (volgens de bucket methode) per gebruiker.
Zorg er voor dat er niet meer data en/of velden in records opgehaald worden dan nodig zijn. Minder data betekend minder dataverkeer en is sneller.
Deze endpoints kenmerken zich doordat ze via de &limit=NNN parameter meer dan 50 records ophalen. Dit kan alleen op sommige endpoints met de '/report/' prefix. Op deze manier kunnen grotere hoeveelheden data opgehaald worden zonder de API te belasten met het doen van grotere hoeveelheden API calls. Voor deze endpoint gelden additionele limieten.
Deze limieten zijn onderhevig aan continue bijstelling en kunnen per situatie verschillen. Ook kan het zijn dat er voor meerkosten (tijdelijk) boven deze limieten gebruik kan worden gemaakt van de API. Op dit moment worden op overschrijden van limieten gestuurd via communicatie vanuit ClockWise.
Als richtlijn is er uitgegaan van een gebruik waarbij elke dag naast het normale gebruik op de API van user apps 1 x de data opgehaald kan worden ten behoeve van externe rapportage. Om deze richtlijn te sturen monitoren we op API gebruik op de report endpoints die de volgende indicatoren overschrijden:
API gebruik op de report endpoints die per dag meer dan 2 x (het aantal uren records + het aantal klanten/projecten/koppelingen records + het aantal medewerker/afdeling records) overschrijden.
API gebruik op de report endpoints die per dag meer dan 8 x de ruwe database grootte aan ongecomprimeerde request data overschrijden.
Vaak is het niet nodig elk uur data op te halen voor een rapportage die wekelijks gecontroleerd wordt. Probeer een realistische inschatting te maken over de verversfrequentie van de data.
Probeer data op te halen op een tijdstip dat er geen of weinig gebruik wordt gemaakt van uw omgeving, bij voorkeur 's nachts. Op die manier hebben gebruikers op de omgeving of andere gebruikers op de server geen last van de vaak lange, processorintensieve rapportage queries.
Het is makkelijk om alle velden in data op te halen, terwijl deze velden niet allemaal gebruikt worden. Probeer daarom het aantal opgehaalde velden zoveel mogelijk te beperken. Dit kan bijvoorbeeld ook door velden bij high load endpoints zoals uren en per resource hetzelfde zijn op te halen bij een call op het resource endpoint in plaats van het uren endpoint en te koppelen via het resource id. Het aangeven van velden die wel of niet getoond moeten worden gaat via de &fields=XXX parameter.
Als dezelfde data voor verschillende rapportages of processen gebruikt wordt, zorg dat deze dan lokaal ge-cached wordt. Dit kan bijvoorbeeld met een zogenaamd datawarehouse. Het warehouse haalt de data op en kan deze vervolgens doorgeven aan de lokaal ingerichte rapportages of processen.
Bij tijd gebaseerde data zijn wijzigingen geconcentreerd rond het nu. Vaak kan een een realistische presentatie van de data die minder API gebruik nodig heeft gemaakt worden door maandelijks alle data, en elke nacht alleen bijvoorbeeld de laatste twee maanden op te halen. Het ophalen van recente data op het uren rapportage endpoint kan bijvoorbeeld door de parameter &date=>=YYYY-MM-DD te gebruiken om data met een datum op of na YYYY-MM-DD op te halen.
Tijdens het ontwikkelen is het vaak niet nodig de data in zijn geheel op te halen. Om het API gebruik te beperken is het beter om dit te doen met een subset van de data.
info@clockwise.info
