API applicatie
Het is mogelijk om een HTTP bron als applicatie toe te voegen. Als je een HTTP applicatie toe wil voegen die nog niet voorgedefinieerd is dan kan je deze volledig zelf definiëren. Kies bij het type applicatie voor ‘API’ om te beginnen met samenstellen.
Een API applicatie kent vier verschillende onderdelen, deze zijn te vinden in de tabbladen bovenaan de pagina.
Het tabblad ‘Token verzoek’ (2) komt pas beschikbaar wanneer het veld ‘Toegangstoken benodigd’ aangevinkt is.
Applicatie toevoegen of bewerken
Het eerste tabblad, "Applicatie toevoegen of bewerken (1)", bevat de basisinformatie van de applicatie. Hier kun je de naam, omschrijving en basis-URL met bijbehorende onderdelen invullen. Meer informatie over de basis onderdelen van een HTTP verzoek vindt je hier.
Bij het onderdeel ‘Basis verzoek’ dient de basis URL opgegeven te worden. Vaak is dit de URL zonder enige endpoints erachter.
Voorbeeld 1: Stel je geeft als basis URL het volgende op:
https://petstore.swagger.io/v2
In de koppeling geef je vervolgens als pad
/pet/1
De totale URL (endpoint) die wordt aangeroepen is dan
https://petstore.swagger.io/v2/pet/1
Zorg er ook voor dat de andere onderdelen van het basisverzoek hier worden ingevuld. Denk hierbij aan statische toegangstokens, content type of gebruikerscertificaten. Door deze informatie hier vast te leggen, hoef je dit later niet op verschillende plaatsen opnieuw te doen.
Als er een toegangstoken vereist is voor de bron, moet het veld 'Toegangstoken benodigd' worden aangevinkt. Je kunt aangeven of het een onbeperkte token statische token is, een onbeperkte dynamische token of een dynamisch token dat bijvoorbeeld elk uur verloopt. Als het veld voor het toegangstoken is aangevinkt, verschijnt er een extra tabblad genaamd 'Token verzoek' bovenaan.
Heb je een statische token die aan elke call toegevoegd dient te worden, maar nooit verandert? Voeg deze dan toe als header aan de basis URL in plaats van gebruik te maken van een dynamische token.
Token verzoek (OAUTH 2.0)
Binnen deze tab kan een toegangstoken worden samengesteld. Roep hiervoor de URL aan voor je token verzoek en voeg alle onderdelen toe die noodzakelijk zijn. Wanneer je dit gedaan hebt klik je op de knop ‘Test token verzoek’. Dit zorgt ervoor dat de verzoek uitgevoerd wordt en je met behulp van de response de autorisatie header kan samenstellen.
Nadat het verzoek is uitgevoerd, ontvang je een response-body waarin zich een element bevindt dat je als token wilt gebruiken. Voeg een header toe met een specifieke sleutel en wijs hieraan de waarde toe die je uit de body hebt verkregen. Verwijs naar deze waarde in je verzoek door de eigenschap tussen dubbele accolades ({{}}) te plaatsen.
Een voorbeeld hiervan:
De header die je hier hebt toegevoegd zal standaard aan elk verzoek van dit type applicatie toegevoegd worden.
Metadata verzoek
Binnen een API applicatie heb je ook de mogelijkheid om metadata vast te leggen. Dit heeft als grote voordeel dat binnen de U-Turn met deze metadata een aantal zaken voor je op de achtergrond geregeld kunnen worden, denk aan bijvoorbeeld de hele lijst met endpoints die een bepaalde API bevat.
Metadata voor een API verwijst naar de informatie die wordt gebruikt om de structuur, functionaliteit en eigenschappen van de API zelf te beschrijven. Het zijn gegevens die extra context en details bieden over hoe de API werkt en hoe deze kan worden gebruikt.
Metadata bevat veelal:
Endpoint-informatie: Dit omvat details over de URL's (endpoints) waarmee de API kan worden benaderd. Het kan aangeven welke HTTP-methoden kunnen worden gebruikt, zoals GET, POST, PUT of DELETE, en welke parameters moeten worden doorgegeven.
Gegevensindeling: Metadata kan aangeven welke indeling wordt gebruikt om gegevens uit te wisselen, zoals JSON (JavaScript Object Notation) of XML (eXtensible Markup Language). Het kan ook de structuur van de gegevens beschrijven, inclusief de beschikbare velden, hun typen en eventuele beperkingen of validatieregels.
Ga na of de applicatie die je toe wil voegen een metadata endpoint heeft of niet. Wanneer deze beschikbaar is kan je deze hier opgeven.
Vul het type metadata (OAS, ODATA of SOAP) in, gevolgd door de versie, methode en URL. Wanneer de metadata geldig is wordt deze opgehaald en omgezet in een resultaat met hierin alle endpoints die vastliggen in de betreffende API.
Wanneer de metadata correct is vastgelegd zal het ophalen en versturen van data in een U-Turn Studio koppeling vergemakkelijkt worden. Je krijgt dan namelijk een lijst te zien met alle endpoints en beschikbare velden die in de metadata vastgelegd zijn.
Variabelen
Op het variabelen tabblad kan je variabelen opgeven die je vervolgens weer kan gebruiken in een koppeling. In sommige situaties moet bijvoorbeeld de authenticatie (token of gebruikersnaam/wachtwoord) in het te versturen bericht worden meegegeven. Dan wil je niet dat je dit voor ieder bericht opnieuw moet opgeven. Je wilt dit op een centrale plek vastleggen zodat in geval van bijvoorbeeld een wijziging, je dit maar op 1 plek hoeft aan te passen. Applicatie gebonden variabelen leg je daarom vast op applicatie niveau.
