In dit artikel wordt beschreven hoe u de functie Vrije Kengetallen kunt gebruiken om data van API’s vast te leggen. Dit kan de API van een technische partner zijn die u voor uw bedrijf gebruikt of uw eigen API die u hebt gebouwd om uw eigen klanten of processen te ondersteunen. Het kan zelfs een aangepaste API zijn die u hebt gebouwd om uw interne bedrijfsstatistieken of platformstatistieken te verzamelen of berekenen. Testtools en monitoringoplossingen helpen u ervoor te zorgen dat uw API’s correct werken, en dit zou een essentieel onderdeel van uw platformactiviteiten moeten zijn. Maar u kunt nog veel meer doen om inzicht te krijgen in de gezondheid van uw platform en bedrijf! Aangepaste API-datamonitoring doet meer dan uptime controleren en datavalidatie uitvoeren – het legt de data vast die door uw API zijn geproduceerd en geeft visueel weer hoe platform- en bedrijfsdata zich in de loop van de tijd ontwikkelen.
API monitoring opnieuw bekeken
U kunt testtools zoals Postman, Insomnia, SoapUI of Swagger UI gebruiken om uw API’s te testen en data te inspecteren voor ad-hoctesten en debuggen. U kunt synthetic monitoring tools gebruiken (zoals Uptrends' API monitoring) om de beschikbaarheid en responstijden continu in de gaten te houden. En niet alleen dat – u wilt een diepgaande contentvalidatie configureren van uw JSON-data (met JSON-expressies) of XML-data (met XPath-query’s), zodat u echt kunt controleren of de door de API geretourneerde data aan uw verwachtingen voldoen – zonder fouten en binnen acceptabele grenzen. Dit helpt ervoor te zorgen dat de processen die afhankelijk zijn van die API’s correct en snel blijven werken. Deze processen kunnen variëren van uw mobiele apps en klantgerichte web-apps tot bedrijfsprocessen in uw backend.
API-data volgen
Stel dat u een REST API hebt die deel uitmaakt van een e-commerce systeem dat producten verkoopt. De volledige productcatalogus bestaat uit verschillende productlijnen die afkomstig zijn van verschillende leveranciers die hun productlijst meerdere keren per dag updaten. U hebt een aantal achtergrondprocessen die uw eigen productcatalogus updaten zodra updates beschikbaar zijn (waarschijnlijk wordt hierbij ook de API van uw leverancier gebruikt). Uw Product API wordt direct gebruikt door uw e-commerce webshop en uw mobiele app.
Controleren of uw productlijst het verwachte aantal producten en categorieën bevat (ten minste een bepaald minimum) is van vitaal belang voor uw bedrijf. U hebt daarover waarschijnlijk een aantal rapporten die afkomstig zijn van uw backend-processen, maar als u dit monitort op basis van uw API-data krijgt u de informatie veel sneller.
Geen probleem – u kunt een Multi-Step API-controleregel (MSA) creëren die een of meer calls naar uw Product API-eindpunt uitvoert en die JSON-geformatteerde data retourneert met het totale aantal producten, de productcategorieën en het aantal producten in elke categorie. U voegt een paar assertions toe die de individuele kenmerken pakken (laten we eerst eens kijken naar TotalProductCount en CategoryCount) en controleren of die aantallen hun minimumwaarden niet overschrijden. TotalProductCount moet bijvoorbeeld altijd groter zijn dan 1500 en CategoryCount moet ten minste 10 zijn. Deze assertions zijn garanties tegen eventuele onopgemerkte productupdatefouten die plotseling een groot deel van uw productvoorraad leegmaken. Als er iets misgaat, wordt u door Uptrends gewaarschuwd en kunt u snel handelen. Dat deel van uw dagelijkse activiteiten is nu gedekt.
Datatrends detecteren
Maar u kunt nog meer doen met deze data. Elke individuele controleregelcheck vertelt u dat uw productcatalogus er gezond uitziet (of niet). Het aantal producten en categorieën is bij elke controle gevalideerd, maar u kunt niet duidelijk zien wat de werkelijke waarden waren. In feite zou het mooi zijn om te kunnen zien hoe het aantal producten fluctueert gedurende de dag (microveranderingen) en gedurende de maand en het jaar (macroveranderingen). Als het aantal producten sneller groeit dan u verwachtte, zou dit kunnen wijzen op een probleem bij het verwijderen van geschrapte producten uit uw database, waardoor uw API en uw mobiele app mogelijk worden vertraagd. Het is lastig om dit te detecteren met eenvoudige assertions – u hebt trendanalyse nodig!
U hebt uw kengetal TotalProductCount al geïdentificeerd in de MSA-assertion, dus is het heel eenvoudig om nu te beginnen met het verzamelen van zijn data als Vrije Kengetallen-data. We gaan dit configureren.
Aangepaste API monitoring configureren
Zorg er eerst voor dat u een werkende MSA-controleregelconfiguratie hebt (wat slechts een enkele stap kan zijn, het hoeft geen multi-step te zijn), zoals besproken in het vorige gedeelte. Ten minste een van de stappen in de MSA-controleregel moet een variabele definiëren die een numerieke waarde van de API-respons vastlegt. U kunt meer lezen over het definiëren van variabelen bij Multi-stap monitoring.
Als u ten minste één variabele in één van uw stappen hebt, kunt u naar beneden scrollen naar het gedeelte Vrije Kengetallen. Daar worden de variabelen die door uw MSA-controleregel zijn geproduceerd weergegeven in de lijst onder Naam van de variabele.
U moet die variabele nu alleen nog “promoveren” tot een Vrije Kengetal door hem onder Naam van het kengetal een naam te geven. Het kan dezelfde naam zijn als de variabele die erin wordt ingevuld, maar misschien wilt u een naam gebruiken die er goed uitziet in rapporten. Als u bijvoorbeeld de variabele TotalProductCount gebruikt, zou de kengetalnaam Total product count waarschijnlijk goed werken.
U kunt maximaal vijf Vrije Kengetallen zoals deze toevoegen binnen één MSA-controleregel. Hebt u er meer nodig, neem dan contact op met Support.
Tot slot slaat u uw controleregeldefinitie op, zodat het nieuwe Vrije Kengetal wordt gevuld!
De data inspecteren en problemen oplossen
Voordat we beginnen met het configureren van grafieken en tabellen, inspecteren we eerst onze nieuwe data. Navigeer naar de controleregel log, zoek uw MSA-controleregel en zoek een recent controleresultaat. Klik erop om het pop-upvenster met het controleresultaat te openen.
In het gedeelte Details van de controle in het pop-upvenster ziet u dat de waarde(n) van uw nieuwe Vrije Kengetal(len) onder de stapresultaten worden weergegeven. Dit geeft u directe toegang tot de individuele Vrije Kengetal-waarden zoals deze werden vastgelegd tijdens de uitvoering van de MSA-controleregel.
Als u de Vrije Kengetal-waarde die u verwachtte niet ziet, ga dan het volgende na: - Hebt u per ongeluk controleresultaten geopend van een oudere controle die is uitgevoerd toen het nieuwe Vrije Kengetal nog niet was gedefinieerd? - Legt uw nieuwe Vrije Kengetal numerieke gehele getallen vast? Als het tekstdata of niet-gehele getallen bevat (zoals 99,9% of 3,1415), wordt het Vrije Kengetal niet vastgelegd. Alleen gehele getallen worden momenteel ondersteund. Neem contact met ons op als u uw wensen wilt bespreken. - Als er iets mis is gegaan tijdens de uitvoering van de MSA-controleregel, is de variabele die in uw Vrije Kengetal wordt ingevoerd mogelijk helemaal niet gemaakt. Onze support engineers kunnen u helpen bij het oplossen van deze problemen.
Rapporten creëren
Nadat u hebt geverifieerd dat uw nieuwe Vrije Kengetal de juiste resultaten oplevert, kunt u een rapport creëren waarin het verloop van uw kengetal wordt weergegeven zodra u voldoende data hebt verzameld. Laten we voor dit voorbeeld een nieuw dashboard creëren (meer over het creëren van dashboards). Klik op Dashboards> Dashboard toevoegen om een splinternieuw dashboard te maken. Klik op een van de lege tegels en scroll omlaag in het menu Nieuwe tegel toevoegen om de tegel Grafiek van Vrije Kengetallen te selecteren.
De nieuwe tegel geeft eerst niets weer. Open de tegelinstellingen en zoek de controleregel die het vrije kengetal bevat. Vouw hem uit om het vrije kengetal aan uw selectie toe te voegen. U ziet dat u meer dan één Vrije Kengetal kunt selecteren: ze worden in één grafiek weergegeven zodat u hun waarden kunt vergelijken.
Op dezelfde manier kunt u de tegel Lijst van Vrije Kengetallen gebruiken om een raster te maken dat de numerieke waarden voor een of meer Vrije Kengetallen weergeeft. Houd er rekening mee dat de weergegeven waarden gemiddelde waarden zijn.
Na het ontwerpen van uw dashboard kunt u het opslaan, exporteren en inplannen voor automatische verzending via e-mail.
Ruwe data inspecteren
De rapporten die we zojuist hebben bekeken, bieden een goede manier om datatrends te bekijken. Maar misschien wilt u dieper graven en met de onderliggende data werken. Als u toegang hebt tot elke individuele kengetalwaarde die we hebben vastgelegd, kunt u plotselinge piekwaarden nauwkeuriger detecteren, min-/max-/mediaan-analyse uitvoeren enzovoort.
Om dit te doen maakt u een exportbestand om alle vastgelegde kengetallen naar een Excel-bestand te downloaden. Navigeer eerst naar het dashboard Controleregel log om de juiste controleregel(s) te selecteren. Open vervolgens de tegelinstellingen voor de tegel Controleregel log. Schakel op de tab Exporteren het selectievakje Vrije Kengetallen in. Klik op Instellen om uw instellingen te bevestigen.
Gebruik tot slot het dashboardmenu (hamburgerpictogram) om het Excel-exportproces te starten (rechtstreeks of via e-mail). In het Excel-bestand ziet u afzonderlijke kolommen voor elk Vrije Kengetal dat is vastgelegd voor uw controleregel(s).
Vrije Kengetal-namen
We raden u aan bij het creëren van een nieuw Vrije Kengetal een naam te gebruiken die gemakkelijk te lezen is in uw rapportage. De naam van het kengetal, gecombineerd met de naam van de controleregel waar deze deel van uitmaakt, wordt weergegeven in de lijst met beschikbare Vrije Kengetallen wanneer u deze toevoegt aan uw aangepaste API-datarapport.
Als u van plan bent meerdere Vrije Kengetallen te creëren die dezelfde soort data vertegenwoordigen (d.w.z. hetzelfde kengetal, maar een andere groep, product, klant enzovoort vertegenwoordigend), is het logisch om ze exact dezelfde naam te geven. U zult ze altijd uit elkaar kunnen houden vanwege de verschillende controleregelnamen.
Wanneer u Vrije Kengetallen creëert, is het goed om deze meteen de juiste naam te geven. U kunt de naam van een kengetal later wijzigen, maar houd er rekening mee dat het als een ander kengetal wordt behandeld zodra het wordt hernoemd: het kengetal wordt op unieke wijze geïdentificeerd door zijn naam.