Een multi-step API-controleregel bestaat uit stappen. Voor elke stap kunt u zowel de HTTP-request- als de responsecomponenten configureren. Dit artikel geeft een overzicht van hoe requests werken en hoe u een HTTP-requestdefinitie kunt instellen.
Request
Binnen een stap ziet u het tabblad Request. U kunt het API-eindpunt definiëren en specifieke informatie instellen bij het verzenden van de request naar de server.
Methode en URL
Als minimumvereiste moet u de juiste HTTP-methode en URL specificeren om te beginnen met het monitoren van uw API.
De beschikbare HTTP-methodes zijn:
GETHEADPOSTPUTPATCHDELETEOPTIONS
De URL is een volledig gekwalificeerde URL, inclusief het schema (“https://” of “http://"), de domeinnaam en het pad voor uw API. U kunt ook queryparameters gebruiken om de door uw request geretourneerde data te filteren, sorteren of aan te passen.
Enkele URL-voorbeelden zijn:
https://galacticresorts.com/api/Destinationshttps://galacticresorts.com/api/Destinations?name=AlphaCygnusIX- U kunt ook een
Voorgedefinieerde variabele gebruiken om een waarde uit de URL op te slaan en deze toe te voegen als
{{BaseUrl}}/api/Destinationsofhttps://galacticresorts.com/api/Destinations/{{ProductId}}.
Request headers
Een HTTP-request bevat request headers. Dit zijn paren van sleutelwaarden die met de request worden meegestuurd om aanvullende informatie aan de server te verstrekken. Deze headers definiëren de parameters van de request, zoals het content type, de autorisatie en eventuele speciale instructies voor hoe de server de request moet verwerken.
Bij het instellen van een requeststap zult u merken dat bepaalde headers standaard zijn toegevoegd. U kunt een nieuwe request header toevoegen, een standaard header overschrijven of vault-items gebruiken.
De afbeelding hierboven toont een voorbeeld van een GET requeststap naar https://www.galacticresorts.com/api/Destinations. Standaard bevat de request headers zoals Host, Accept-Encoding en Content-Length. De waarden voor de headers Host en Content-Length worden bepaald bij het verzenden van de request. Daarnaast is de header Accept ingesteld op application/json en is de standaard header Accept-Encoding overschreven.
U kunt ook andere headers toevoegen, zoals Content-Type. De meest voorkomende contenttypes zijn application/json voor JSON-data, text/xml voor XML-data en application/x-www-form-urlencoded voor webform-data. Als uw API authenticatie vereist, voegt u een Authorization-header toe samen met de juiste data in het veld Waarde.
Nieuwe headers toevoegen
Om een nieuwe header toe te voegen doet u het volgende:
- Klik op Request header toevoegen.
- Geef de naam van de header op. Bijvoorbeeld:
Content-Type. - Geef de waarde van de header op. Bijvoorbeeld:
application/json.
Een standaard header overschrijven
Om een standaard header te overschrijven doet u het volgende:
- Klik op Request header toevoegen.
- Geef een bestaande headernaam op. Bijvoorbeeld:
Accept-Encoding. - Geef een nieuwe headerwaarde op. Bijvoorbeeld:
gzip, compress. De standaardheader wordt nu doorgestreept weergegeven, wat aangeeft dat deze is overschreven.
Request body
Wanneer u een POST, PUT, PATCH, HEAD, OPTIONS of DELETE request specificeert, bevat de Request body de specifieke content of payload als onderdeel van de requestdefinitie.
Er zijn verschillende formaten voor de request body waaruit u kunt kiezen bij het verzenden van data als onderdeel van de request:
- Platte tekst — hiermee kunt u platte tekst verzenden zonder dat er opmaak is toegepast.
- Bestand uploaden (als form-data) — hiermee kunt u een bestand, zoals afbeeldingen en documenten, verzenden vanuit de Vault in form-data-formaat.
- Bestand uploaden (als binary) — hiermee kunt u een bestand, zoals afbeeldingen en documenten, verzenden vanuit de Vault in een onbewerkt binair dataformaat.
- Multi-part form — hiermee kunt u meerdere types content in verschillende formaten verzenden. Bijvoorbeeld: het gelijktijdig verzenden van plattetekstentries en bestanden die zijn opgehaald uit de Vault.
Raadpleeg Vault-items gebruiken als bestandsuploads voor meer informatie over het gebruik van vault-items in de request body.
Authenticatie
Als uw API is beveiligd en authenticatie vereist op verzoek van de server, kunt u kiezen uit de onderstaande beschikbare authenticatieopties:
- Basic authentication — hiermee kunt u een gebruikersnaam en wachtwoord opgeven, deze worden gecodeerd in een Base64-formaat en naar de API-server verzonden.
- NTLM (Windows) authentication — hiermee kunt u een gebruikersnaam en wachtwoord opgeven voor authenticatie met Windows-servers of -domeinen.
- Digest authentication — hiermee kunt u een gebruikersnaam en wachtwoord opgeven, deze worden MD5-gehasht en naar de API-server verzonden.
- Set up OAuth based authentication — hiermee kunt u een aangepaste authenticatie gebruiken, met name OAuth 2.0.
Als u uw bestaande vault-items wilt gebruiken om authenticatie voor uw request in te stellen, raadpleeg dan de sectie Vault-items gebruiken hieronder. Raadpleeg voor meer informatie Multi-step monitoring Authenticatie.
Clientcertificaten
Als uw API vereist dat clients zich identificeren met een clientcertificaat, gebruik dan een van de volgende opties:
- Uptrends clientcertificaat — gebruikt een Uptrends-certificaat, dat wordt meegestuurd wanneer de HTTP-request wordt verzonden.
- Eigen clientcertificaat — hiermee kunt u uw eigen clientcertificaat toevoegen, opgeslagen in de Vault, dat wordt meegestuurd wanneer de HTTP-request wordt verzonden.
Raadpleeg Multi-step API - Clientcertificaten voor meer informatie.
HTTP- en TLS-versies
Voor een betere controle over uw API-calls, kunt u de HTTP- en TLS-versies opgeven voor aanvullende beperkingen. Raadpleeg voor meer informatie het knowledgebase-artikel HTTP- en TLS-versies.
HTTPS-verbinding
Telkens wanneer er een API-call wordt gedaan, verifieert uw server standaard het TLS- of SSL-certificaat. Als u certificaatvalidatie wilt overslaan en gerelateerde fouten wilt negeren, selecteert u gewoon deze optie.
Foutafhandeling
Selecteer Foutafhandeling op het tabblad Request om de fouten die binnen een stap zijn opgetreden te negeren. Als een controleregel fouten binnen de stap aantreft, slaat de controleregel de stap gewoon over. Vervolgens worden de resterende stappen uitgevoerd totdat alle stappen zijn voltooid. Raadpleeg voor meer informatie het knowledgebase-artikel Foutafhandeling.
Vault-items gebruiken
De Vault is een centrale opslag waarmee u inloggegevens en andere gevoelige informatie kunt opslaan en beheren, zodat u deze in uw gehele monitorconfiguratie kunt gebruiken.
Stel dat u zich wilt authenticeren met een specifieke gebruikersnaam of wachtwoord bij het doen van een request aan de server. Gebruik dan eenvoudigweg een vault-item zoals een set vault-inloggegevens als onderdeel van de request body en de request headers. U kunt ook het veld Authenticatie gebruiken, zoals eerder vermeld.
Om een set vault-inloggegevens te gebruiken, gebruikt u de volgende syntaxis, afhankelijk van welke waarde vereist is:
- Gebruikersnaam:
{{@VaultItem.<itemGuid>.Username}} - Wachtwoord:
{{@VaultItem.<itemGuid>.Password}}
U vindt de <itemGuid> wanneer u naar het menu navigeert en een specifiek vault-item selecteert. Kopieer de waarde achter VaultItemGuid= uit de URL. Bijvoorbeeld: 91303546-79e1-4f62-9b62-8973323dfe3b in https://app.uptrends.com/report/VaultItem?VaultItemGuid=91303546-79e1-4f62-9b62-8973323dfe3b.
Zoals te zien is in de afbeelding, werden de gebruikersnaam en het wachtwoord opgehaald als een set vault-inloggegevens. Beide werden gebruikt in de URL, de requestheader- en de requestbody-definitie.
Vault-items gebruiken als bestandsuploads
Met multi-step API-controleregels kunt u bestanden uploaden vanuit de Vault als onderdeel van de request-definitie.
Volg deze stappen om een bestand uit de vault te uploaden:
- Selecteer in Request > Request body een van de volgende opties:
- Bestand uploaden (als form-data)
- Bestand uploaden (als binary)
- Multi-part form
- Klik op Bestand uit de vault toevoegen.
- Kies het juiste bestand dat is opgeslagen in de Vault.
- Klik op om het bestand toe te voegen.
Het bestand is toegevoegd. U hoeft geen request headers op te geven, aangezien sommige headers, zoals Content-Type: multipart/form-data automatisch worden toegevoegd en ingesteld met de juiste waarde.
U kunt controleren of het uploaden van het bestand is geslaagd door een test uit te voeren in de controleregel. U ziet de resultaten in Request headers en content:
Aangepaste scripting
De onderdelen request en response van een stap kunnen optioneel worden uitgebreid met Aangepaste scripting op de tabbladen Pre-Request en Post-Response. Hiermee kunt u scripts uitvoeren die in JavaScript zijn geschreven om aangepaste logica uit te voeren en diepgaande functionele tests uit te voeren. Naast de volledige reeks mogelijkheden die standaard JavaScript biedt, kunt u ook Snippets gebruiken. Dit zijn voorgedefinieerde scripts van Uptrends waarmee u de correcte functionaliteit en het gedrag van uw API’s kunt verifiëren.