1. Support
  2. Knowledge Base
  3. API Monitoring
  4. Multi-step API monitoring configureren

Multi-step API monitoring configureren

We vernieuwen onze gebruikersinterface. Sommige informatie is nog niet aangepast. Lees meer.

Om uw API adequaat te monitoren moet u vaak gebruikmaken van multiple HTTP requests. Meestal zult u een reeks requests willen configureren, waarbij iedere nieuwe request gebruikmaakt van een of meer stukjes data afkomstig van een vorige request om zijn taak uit te voeren.

Mogelijke redenen om een reeks HTTP requests te doen zijn:

  • Uw API vereist geverifieerde toegang. Om een method aan te roepen in de daadwerkelijke API moet een API client zich eerst authenticeren (bijvoorbeeld door het gebruik van OAuth authentication).
  • U wilt een functioneel scenario in uw API testen dat bestaat uit meerdere stappen die meestal door uw eindgebruikers in een bepaalde volgorde worden uitgevoerd.
  • Een van uw HTTP requests retourneert een redirect naar een andere URL, maar u wilt die respons inspecteren voordat de redirect wordt gevolgd.

Voor al deze scenario’s is Multi-step API monitoring heel geschikt!

Een API scenario kan beginnen als slechts een enkele stap, maar u kunt zelf meer stappen toevoegen en uw scenario’s zelfs later uitbreiden. U hebt volledige controle over de complete HTTP request content. Functies omvatten:

Deze functies helpen u ervoor te zorgen dat uw API zich correct gedraagt en binnen de door u gespecificeerde limieten presteert. De stapsgewijze aanpak stelt u in staat om zeer krachtige scenario’s op te zetten zonder complexiteit toe te voegen. Zolang u maar weet hoe uw API zich moet gedragen, hoeft u niet te kunnen programmeren om aan de slag te gaan met API monitoring.

Een multi-step API controleregel creëren

Om een multi-step API controleregel toe te voegen doet u het volgende:

  1. Klik op + Controleregel toevoegen in het menu Controleregels.
  2. Kies Multi-step API in het menu Type.
  3. Geef uw controleregel een Naam.
  4. Ga naar het tabblad Stappen om de details voor elke stap in de voeren.

Uw nieuwe controleregel begint met een (lege) stap. Ga door en klik op de knop + Request-stap toevoegen om extra stappen toe te voegen. U zult zien dat de lijst met stappen groeit. Klik op een stap om de details ervan te bewerken. Om een stap te verwijderen klikt u op de knop Stap verwijderen die verschijnt als u met de muisaanwijzer over de stappenlijst beweegt.
Klik op de knop Stap dupliceren om een kopie te maken van een bestaande stap. U kunt ook de volgorde van de stappen wijzigen met de knoppen Verplaats stap omhoog en Verplaats stap omlaag.

Een request-stap configureren

Bekijk de eerste stap van onze controleregel, u ziet twee tabbladen aan de rechterkant van het scherm: Request en Response. Laten we ze bekijken.

Request

Het tabblad Request bevat alle data die nodig zijn om de daadwerkelijke HTTP request in de stap uit te voeren. Doe ten minste het volgende:

  1. Kies de juiste HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD of OPTIONS. Als u een andere methode nodig hebt, neem dan contact met ons op.
  2. Vul de URL in voor de request. Gebruik een volledig gekwalificeerde URL, inclusief het protocol (“https://” of “http://"), de domeinnaam en het pad voor uw API, en eventuele query string parameters die u wilt opnemen.
  3. Voer optioneel een korte beschrijving in voor deze stap. Deze beschrijving verschijnt in de resultaten van de controleregelcheck.

Request body

Bij het opgeven van een POST, PUT, PATCH, DELETE, HEAD of OPTIONS request, verschijnt het veld Request body. Specificeer de data die u wilt verzenden als onderdeel van de request (hoogstwaarschijnlijk JSON data, XML data of gecodeerde formulierdata). In de meeste gevallen verwacht uw server dat u de indeling specificeert van de data die u verzendt, zodat het weet hoe deze data moeten worden gelezen en gedeconstrueerd. Om dit te doen moet u een Content-Type request header toevoegen zoals in de volgende alinea wordt beschreven.

Request headers

Een HTTP request bevat meestal enkele request headers om het formaat van de data die worden verzonden te specificeren, of om verder te beschrijven wat voor een soort respons verwacht wordt. Bij het configureren van een request stap zult u merken dat bepaalde headers automatisch worden toegevoegd. Deze headers bestaan uit een standaardset, afhankelijk van het type request dat u doet (GET-requests hebben bijvoorbeeld een andere set headers dan POST-requests). Een standaard header kan worden overschreven (met uitzondering van de Content-Length header) door simpelweg een nieuwe header toe te voegen met precies dezelfde naam als de bestaande, maar met een andere waarde.

Er kunnen ook nieuwe headers worden toegevoegd. Bijvoorbeeld, om de eerder genoemde Content-Type header toe te voegen, volgt u deze stappen:

  1. Klik op de knop Request header toevoegen om een request header key en waarde toe te voegen.
  2. Voer Content-Type in als de header key.
  3. De juiste header waarde is afhankelijk van de data die u verzendt. De meest voorkomende content types zijn application/json voor JSON data, text/xml voor XML data en application/x-www-form-urlencoded voor webformulierendata.

Evenzo, als uw API vereist dat u authenticatie opneemt, voegt u een Authorization header toe samen met de juiste data in het veld Waarde.

Voorbeelden van request headers

De afbeelding hierboven toont een voorbeeld van een request stap. Let op het volgende:

  • Het is een POST request naar https://www.galacticresorts.com/api/Reservation
  • De standaard headers die voor deze request zijn ingesteld, zijn:
    • Host
    • Accept-Encoding
    • Connection
    • Content-Length
  • De waarden voor de headers Host en Content-Length worden bepaald bij het verzenden van de request.
  • Handmatige headers Content-Type en Authorization zijn toegevoegd om respectievelijk het dataformaat te specificeren en de benodigde inloggegevens te verstrekken.
  • Standaard header Connection is overschreven.
  • De request body bevat wat x-www-form-urlencoded inhoud.

Authenticatie

Veel API’s zijn beveiligd en alleen toegankelijk door inloggegevens te verstrekken. Als uw API gebruikmaakt van authenticatie op het HTTP-protocolniveau, kies dan uw type authenticatie (Basic, NTLM or Digest) en vul de bijbehorende gebruikersnaam en wachtwoord in. Als alternatief kunt u een op OAuth gebaseerde authenticatie instellen met afzonderlijke stappen. Meer informatie over het instellen van ingebouwde of aangepaste authenticatie.

Inloggegevens uit de vault gebruiken

Het is mogelijk om op elk punt verwijzingen naar vault-inloggegevens te gebruiken als onderdeel van de request body, request headers of als de waarde voor uw gebruikersnaam/wachtwoord onder Authenticatie. Gebruik de volgende syntaxis om naar een vault-item te verwijzen: {{@VaultItem.<itemGuid>.Password}} of {{@VaultItem.<itemGuid>.Username}} afhankelijk van welke waarde vereist is. Om de itemGuid te vinden navigeert u naar het vault-item met de inloggegevens en kopieert u vervolgens het laatste deel van de URL in de URL-balk van uw browser.

Voorbeelden van verwijzingen naar vault-items

Response

Het tabblad Response bevat alle opties voor het uitvoeren van controles op responsdata (met behulp van Assertions) en het verwerken van die data ter voorbereiding op de volgende stap (met behulp van Variabelen).

Assertions

Het definiëren van uw stappen en het invoeren van de juiste data in deze stappen is de basis voor een bruikbare opzet. Het is echter ook belangrijk om naar de resultaten van elke stap te kijken. Alleen het aanroepen van een reeks URL’s is niet zinvol als ze niet de juiste resultaten terugsturen. Assertions helpen u bij deze gezondheidscontroles.

Assertions zijn controles die u kunt uitvoeren om te verifiëren dat de respons zich in een bepaalde stap gedraagt als verwacht, bijvoorbeeld, door zijn content te controleren of te verifiëren of het binnen een bepaalde hoeveelheid tijd is opgehaald. Net als bij variabelen, geeft u de bron voor de controle op, bijvoorbeeld een JSON property van de JSON response body, een XPath query op de XML response body, of zelfs alleen de statuscode van de response, de duur ervan of de lengte van de inhoud.

Meer voorbeelden van Assertions: lees onze uitgebreide handleiding voor het definiëren van assertions.

Variabelen

Wanneer u multi-step scenario’s aan het opzetten bent, is het waarschijnlijk dat ten minste één van die stappen afhankelijk is van invoer die tijdens een vorige stap is opgehaald. Door die invoer vast te leggen, tijdelijk op te slaan en mee te nemen naar de volgende stappen, creëert u een natuurlijke progressie van verbonden stappen, zonder dat u enige code hoeft te schrijven.

Dat is precies wat u met variabelen kunt doen! Elke stap kan nieuwe variabelen maken en heeft toegang tot variabelen die door andere stappen zijn gemaakt, zodat u data kunt hergebruiken die eerder in het scenario zijn vastgelegd.

U kunt definiëren waar een variabele vandaan moet komen: waarschijnlijk een bepaalde waarde uit JSON- of XML-data, maar het vastleggen van response headers of zelfs van data van een redirect is ook mogelijk. Nadat een variabele is gedefinieerd, kunt u deze eenvoudig overal in uw multi-step-opzet gebruiken door er met zijn naam naar te verwijzen: {{my-variable}}.

Meer voorbeelden van: Variabelen definiëren en gebruiken.

Opnieuw proberen tot het gelukt is

In sommige gevallen kan het zijn dat uw API enige tijd nodig heeft om een binnenkomende request te verwerken voordat hij kan reageren met de melding dat het is gelukt. Stel dat u bijvoorbeeld een bestand voor verwerking uploadt naar uw API. Tijdens de verwerking reageert de API op requests over de status met {"result":"processing"} in een JSON-body. Zodra de verwerking is voltooid, begint de API in plaats daarvan te reageren met {"result":"success"}. In dergelijke gevallen kunt u de controleregel configureren om de API te blijven peilen totdat deze met succes reageert door de functie Opnieuw proberen tot het gelukt is te gebruiken.

Deze functie zorgt ervoor dat de controleregel de stap opnieuw doet als een of meer van de assertions (aannames) in de stap (zoals Response body als JSON result Is gelijk aan success voor het hierboven genoemde voorbeeld) mislukt. U kunt instellen hoeveel keer de controleregel het opnieuw moet proberen (met een maximum van 50 keer). Elke nieuwe poging wordt uitgevoerd met een wachttijd van één seconde ertussen. Schakel eenvoudig de optie in het tabblad Response van een stap in en stel in hoeveel keer de stap opnieuw moet worden gedaan.

MSA stap opnieuw proberen

De controleregel zal de stap opnieuw blijven proberen ofwel totdat het maximum aantal pogingen is bereikt ofwel totdat elke assertion is geslaagd. Vanaf dat punt zal de controleregel gewoon verdergaan en de rest van de stappen in volgorde uitvoeren. Als het maximum aantal pogingen is bereikt en er nog steeds ten minste één assertion mislukt, rapporteert de controleregel een fout in het controleregel-log.

Overigens blijven de kosten van de MSA-controleregel gelijk, ongeacht het aantal pogingen.

Bestandsuploads configureren

Met Multi-step API-controleregels kunt u bestanden uploaden vanuit uw vault als onderdeel van een van uw request-stappen. Elke HTTP-stap die u configureert in de Multi-step API-controleregel die een request body bevat, kan een bestandsupload of een gewone request met platte tekst zijn. Bestanden worden verzonden als multipart/form-data-inhoud. Volg deze stappen om dit in te stellen:

  1. Upload het betreffende bestand naar uw vault. De maximale bestandsgrootte is 2 MB.
  2. Voeg in de instellingen van uw Multi-step API-controleregel een request-stap toe of gebruik een bestaande stap om het uploaden van het bestand uit te voeren.
  3. In het tabblad Request van de stap die het uploaden van het bestand moet uitvoeren, stelt u de request-methode in op POST, PUT of PATCH (afhankelijk van wat u nodig heeft) en vult u de request-URL in.
  4. Selecteer onder Request body de optie Een bestand uit de vault uploaden.
  5. Klik op de knop Bestand uit de vault toevoegen die verschijnt.
  6. Kies het juiste bestand uit de Vault-bestandsuploadlijst en klik op de knop Selecteren. Bestandsuploadkiezer
  7. Het is niet nodig om specifieke request headers toe te voegen. We stellen automatisch een request header in voor Content-Length en stellen Content-Type: multipart/form-data in met de juiste boundary (grens). Voorbeeld headers voor bestandsupload

Een Wachtstap configureren

Als u een reeks Request-stappen aan uw controleregel hebt toegevoegd, wordt elke stap uitgevoerd zodra de vorige stap is voltooid, zonder vertraging. Echter, deze onmiddellijke uitvoering kan voor sommige scenario’s iets te snel zijn.

Denk bijvoorbeeld aan een API-methode die vraagt een rapportbestand te genereren. De API start een backendproces dat het bestand genereert en de caller instrueert een tweede request te sturen om het nieuwe bestand te downloaden. Het genereren van het bestand kan zo’n twee seconden duren, dus de caller moet enkele seconden wachten voordat de tweede request wordt verstuurd. Wordt deze te snel verstuurd, dan zal de tweede request mislukken omdat het gegenereerde bestand nog niet gereed is.

Voor dit scenario is het belangrijk om te wachten voordat Multi-step API om de tweede request vraagt. Om een vertraging toe te voegen kunt u een afzonderlijke Wachtstap invoegen. Met een Wachtstap kunt u het aantal milliseconden opgeven dat moet worden vertraagd. Om bijvoorbeeld 3 seconden te wachten geeft u 3000 milliseconden op als de wachttijd. Het rapport bevat de extra wachttijd in de totale tijdsduur voor de controleregel.

Om een wachtstap toe te voegen klikt u gewoon op de knop + Wachtstap toevoegen en specificeert dan het aantal milliseconden dat u wilt wachten. Zo nodig kunt u de wachtstap naar de juiste plek in uw scenario verplaatsen met de knoppen Verplaats stap omhoog/omlaag.

De wachttijd voor een wachtstap is beperkt tot 60 seconden: een wachtstap is niet bedoeld voor het monitoren van een langlopende taak die enkele minuten of uren duurt. Als de controleregel de maximale totale uitvoertijd overschrijdt, stopt de controle met uitvoeren en rapporteert een fout.

Het toevoegen van een wachtstap aan uw controleregel kost u niets. Uptrends baseert de kosten van een Multi-step API-controleregel alleen op het aantal Request-stappen.

Resultaten, errors en alerts van een multi-step-controleregel

Multi-step API-controleregels gedragen zich hetzelfde als elke andere controleregel. Elke controle verschijnt in de controleregel log en geeft uitgebreide informatie weer over elke afzonderlijke stap. Voor elke stap bestaat deze informatie uit:

  • de totale duur van de stap (in milliseconden)
  • de URL die werd uitgevoerd gedurende die stap
  • de HTTP statuscode die is geretourneerd
  • het resultaat voor iedere assertion (slagen of mislukken)
  • de request headers en content die we hebben verzonden
  • de response headers en content die we hebben ontvangen

Als er tijdens een van de stappen een probleem optreedt, of als een van de assertions die u hebt gedefinieerd mislukt, zal de monitor mislukken en een error rapporteren. Zoals gewoonlijk kunnen deze errors alerts genereren op basis van uw alertdefinities.

Door deze website te gebruiken, stemt u in met het gebruik van cookies in overeenstemming met ons Cookiebeleid.