Endpoints testen met Try It!

Try It! is de interactieve API van Document360, direct ingebed in je gepubliceerde API-referentie. Het stelt ontwikkelaars in staat echte verzoeken naar je API-eindpunten te sturen en live antwoorden te zien zonder de documentatie te verlaten of code te schrijven.

Dit artikel legt uit hoe de Try It!-console werkt in je gepubliceerde API-referentie — hoe je deze opent, een verzoek bouwt en verstuurt, het antwoord leest, en wat de console wel en niet ondersteunt. Voor details over het configureren van elke authenticatiemethode, zie Authorizing requests in de Try It-console.

Wat Try It! doet

Vanaf elke endpointpagina in je gepubliceerde API-referentie kunnen ontwikkelaars:

• Open een interactieve console inline op het eindpunt, zonder de pagina te verlaten
• Vul pad- en queryparameters, headers en (voor schrijfmethoden) een requestbody in
• Verstil authenticatiegegevens voor het beveiligingsschema van het eindpunt
• Stuur een live verzoek en bekijk de echte reactie — status, timing, headers en hoofdtekst

Het openen van de Try It-console

Op elke endpointpagina verschijnen de methode en URL van het endpoint bovenaan, met een Try It-knop ernaast.

1. Klik op Probeer het. De interactieve console opent inline, direct onder de endpoint-URL.
2. Bouw je verzoek op met de hieronder beschreven tabbladen en klik vervolgens op Verzenden.
3. Als je klaar bent, klik je op het pictogram 'Sluit Probeer het' (X) om de console in te klappen en verder te gaan met het lezen van de documentatie.

De console opent ter plaatse - je blijft de hele tijd op dezelfde endpointpagina, met de documentatie erboven nog zichtbaar.

Een verzoek opbouwen

De request builder is georganiseerd in tabbladen. Welke tabbladen verschijnen hangt af van de HTTP-methode van het eindpunt:

• Params — pad- en queryparameters gedefinieerd voor het eindpunt. Vereiste parameters zijn gemarkeerd en elk toont zijn beschrijving vanuit je specificatie.
• Autorisatie — de authenticatiemethode en inloggegevens voor het beveiligingsschema van het eindpunt. Zie Autorisatieverzoeken in de Try It-console.
• Headers — verzoekheaders.
• Lichaam — de verzoeklading. Dit tabblad verschijnt alleen voor methoden die een body nemen, zoals POST, PUT en PATCH. Het wordt niet getoond voor GET-verzoeken.

Terwijl je de tabbladen invult, bouwt de console het verzoek op de achtergrond op. Je kunt het samengestelde verzoek op elk moment bekijken in het Verzoek-paneel rechts, en het equivalente codevoorbeeld in het Code-paneel bekijken.

Samenwerken met het verzoekorgaans

Voor endpoints die een body accepteren, geeft het tabblad Body je een volledige editor met tools om je payload op te bouwen en te valideren.

• geen / raw — kies of je geen lichaam (none) of een ruwe payload (raw) stuurt.
• Mediatype — selecteer het inhoudstype voor de hoofdtekst, zoals application/json.
• Voorbeeld — voeg een kant-en-klaar voorbeeldpayload in voor het eindpunt, gegenereerd vanuit jouw specificatie.
• Invullen vanuit schema — vul de editor met een voorbeeldbody die is opgebouwd uit het verzoekschema van het eindpunt. Dit overschrijft de huidige inhoud van de editor.
• Verschoon — hervorm de body met de juiste inkeping, zodat een verkleinde of rommelige lading leesbaar wordt.
• Herstel een recent verzonden lichaam — breng een lichaam terug dat je eerder in deze sessie hebt gestuurd. Dit herstelt lichamen die je daadwerkelijk hebt verzonden, zodat je snel kunt terugkeren naar een vorige werkende payload zonder deze opnieuw te typen.
• Schakel woordwrap in — wikkel lange regels in de editor zodat je ze kunt lezen zonder horizontaal te scrollen.

Validatie tegen het schema

De body editor valideert je payload tegen het schema van het endpoint terwijl je typt — niet alleen voor geldige JSON, maar ook voor de vraag of de payload daadwerkelijk overeenkomt met wat het endpoint verwacht.

Dit vangt twee verschillende soorten problemen op:

• Syntaxisfouten — de payload is niet goed gevormd, bijvoorbeeld een ontbrekende komma of dubbele punt. Deze verschijnen als berichten zoals "Colon verwacht" of "Verwachte komma".
• Schemafouten — de payload is geldige JSON, maar komt niet overeen met het schema. Als een veld bijvoorbeeld een geheel getal verwacht en je een string aangeeft, markeert de editor "Onjuist type. Verwacht...". Het aanleveren van een veld dat het schema niet toestaat, wordt gemarkeerd als "Property is not allowed."

Wanneer er problemen worden gevonden, verschijnt er onder de editor een gedeelte voor validatieproblemen met het aantal problemen. Gebruik Spring naar het volgende probleem om direct naar elk probleem in de editor te gaan, en vergroot de lijst om elk probleem tegelijk te zien.

Dit betekent dat een payload perfect geldig JSON kan zijn en toch gemarkeerd kan worden — omdat Try It! het controleert met het daadwerkelijke schema van je API, waarbij mismatches worden opgemerkt voordat je het verzoek verstuurt in plaats van nadat de server het afwijst.

Het verzoek versturen en het antwoord lezen

Zodra je verzoek klaar is, klik je op Verzoek verzenden. De console stuurt een live verzoek naar je API en toont het resultaat in het responsgebied rechts.

De reactie omvat:

• Status — de HTTP-statuscode werd teruggegeven, zoals 200, 401, of 404.
• Tijd — hoe lang het verzoek duurde, in milliseconden.
• Grootte — de grootte van het responslichaam.
• Body- en headertabbladen — wissel tussen de responspayload en de volledige set responsheaders die door de server worden teruggestuurd.

Je kunt de verzoek- en responspanelen verkleinen door de scheidingsschakelaar ertussen te slepen, waardoor er meer ruimte is aan de kant waar je werkt.

Je werk is gered

Terwijl je in de console werkt, bewaart Try It! je input zodat je die niet verliest als je rondbeweegt:

• Parameters, headers, de requestbody, het geselecteerde mediatype en het actieve tabblad worden behouden terwijl je van eindpunt wisselt en zelfs als je de console tijdens dezelfde sessie sluit en opnieuw opent.
• Inloggegevens en de laatste reactie worden alleen bewaard voor de actieve sessie en worden niet behouden. Inloggegevens worden ook verborgen in de verzoekpreview voor de beveiliging.

Authenticatie

Ontwikkelaars geven inloggegevens in het tabblad Autorisatie , met het schema dat uw API definieert — API-sleutel, HTTP Basic, HTTP Bearer, OAuth 2.0 of OpenID Connect. Try It! leest de schema's uit je OpenAPI-specificatie en toont de juiste velden voor elk.

Voor volledige details over elke methode — inclusief hoe je ze definieert in je specificatie en hoe OAuth 2.0-aanmelding werkt in de console – zie Authorizing requests in de Try It-console.

Met behulp van variabelen

Variabelen stellen ontwikkelaars in staat een waarde één keer op te slaan en deze te hergebruiken over eindpunten met een {{placeholder}} — handig voor waarden zoals een ID of token die herhaald worden over veel verzoeken. Je kunt een variabele in elk veld invoegen, en de Request preview toont dat deze tot de werkelijke waarde is opgelost.

Voor hoe je variabelen maakt, beheert en hergebruikt, zie Variabelen gebruiken in de Try It-console.

Vereisten voor Try It! om te verschijnen

Try It! verschijnt alleen op een endpointpagina wanneer je API-specificatiebestand het volgende correct definieert:

• Een server-URL - het servers gedeelte van je specificatie moet minstens één geldige basis-URL bevatten.
• Een servervariabele (optioneel) - indien gebruikt, moet de variabele naast de URL worden gedefinieerd.

Als de server-URL ontbreekt, zal de Try It!-knop niet zichtbaar zijn op de kennisbanksite.

Correct server-URL-formaat

servers:
  - url: https://api.yourdomain.com
    description: Production

Voor API's met meerdere regio's, definieer meerdere items:

servers:
  - url: https://api.yourdomain.com
    description: Global

  - url: https://api.us.yourdomain.com
    description: US region

What Try It! ondersteunt geen ondersteuning

• Webhooks - Try It! is niet beschikbaar voor webhook-definities. Webhook-pagina's tonen het payloadschema en een voorbeeld, maar kunnen geen testverzoeken versturen.

FAQ