API-fundamenten

De API van Document360 biedt je een complete, end-to-end oplossing voor het publiceren, beheren en testen van API-referenties. Of je nu een startup bent die je eerste publieke API uitbrengt of een onderneming die tientallen interne microservices onderhoudt, Document360 verandert je OpenAPI-specificatie in gepolijste, interactieve ontwikkelaarsdocumentatie zonder dat er aangepaste tools of handmatige opmaak nodig zijn.

De lezerservaring

Wanneer je een API-referentie publiceert, komen ontwikkelaars uit op een interactieve, drie-panelen pagina — niet op een statisch document. Het begrijpen van deze lay-out helpt je om je te visualiseren wat je lezers daadwerkelijk zien, en wijst je naar het artikel dat elk deel diepgaand uitlegt.

• Links - navigatieboom. Elk eindpunt in je specificatie, gegroepeerd per tag in categorieën en subcategorieën, met een methodelabel (GET, POST, PUT, PATCH, DELETE) naast elk. Lezers filteren op naam om snel naar een eindpunt te springen.
• Centrum - documentatie. De beschrijving van het eindpunt, pad- en queryparameters, het requestbody-schema en authenticatievereisten - allemaal gegenereerd vanuit jouw specificatie.
• Rechts - Code- en Responspanelen. Kant-en-klare voorbeelden van verzoeken en voorbeeldantwoorden, naast de documentatie.

Codepaneel

Het Codepaneel toont een klaar om te kopiëren verzoekvoorbeeld voor het eindpunt, en lezers kunnen de taal aanpassen aan hun stack. Er zijn zes talen beschikbaar:

• cURL
• Shell
• Python
• Java
• JavaScript
• C#

Elke sample wordt bijgewerkt om het echte pad, parameters en authenticatie van het endpoint weer te geven, zodat een lezer het direct naar zijn eigen omgeving kan kopiëren.

Responspanel

Het Antwoordpaneel toont voorbeeldantwoorden voor het eindpunt, georganiseerd op statuscode (bijvoorbeeld succes- en foutantwoorden zoals 200, 401, 403, 404, 422, 429, , 500). Lezers kiezen een statuscode om de vorm van het antwoord te zien die ze in elk geval kunnen verwachten, wat het makkelijker maakt om zowel succes- als foutpaden in hun integratie te beheren.

Probeer het eens

Try It verandert de referentie van iets dat lezers lezen in iets dat ze kunnen gebruiken. Het opent een interactieve console inline op elk eindpunt, zodat ontwikkelaars een echt verzoek kunnen sturen en de live respons kunnen zien - status, timing, headers en body - zonder de pagina te verlaten of code te schrijven. Zie Endpoints testen met Try it! voor de volledige walkthrough.

Authenticatie

Lezers geven inloggegevens direct in de Try It-console met het schema dat je API definieert — API-sleutel, HTTP Basic, HTTP Bearer, OAuth 2.0 of OpenID Connect. Try It leest de schema's uit je specificatie en toont de juiste velden voor elk. Zie Autorizing requests in de Try It-console voor details over elke methode.

Variabelen

Variabelen stellen lezers in staat een waarde één keer op te slaan, zoals een ID of een token, en deze te hergebruiken op elk eindpunt in de referentie met een {{placeholder}}. Dit bespaart het opnieuw typen van veelvoorkomende waarden terwijl ze van het ene eindpunt naar het andere gaan. Zie Variabelen gebruiken in de Try It-console.

Eddy AI

Eddy AI is ingebouwd in de referentie zodat lezers vragen kunnen stellen over een endpoint - hoe het werkt, hoe te authenticeren, of een codevoorbeeld in een specifieke taal en antwoorden kunnen krijgen zonder de pagina te verlaten. Zie Using Eddy AI in de API-referentie.

Wat is API-documentatie en waarom is het belangrijk?

API-documentatie is de technische referentie die ontwikkelaars precies vertelt hoe ze met je API moeten omgaan: welke endpoints bestaan, welke parameters ze accepteren, welke antwoorden ze teruggeven en hoe authenticatie werkt. In tegenstelling tot algemene kennisbasisartikelen volgen API-documenten een strikt, gestructureerd formaat dat is afgeleid van een machineleesbaar specificatiebestand.

Waarom het belangrijk is:

• Vermindert de integratietijd. Clear docs verminderen de onboarding van dagen naar uren. Ontwikkelaars besteden minder tijd aan gokken en meer aan bouwen.
• Vermindert de ondersteuningslast. Wanneer de artsen de vragen "hoe authenticeer ik?" en "wat betekent een 422?" beantwoorden, krijgt je team minder tickets.
• Bouwt het vertrouwen van ontwikkelaars op. Onvolledige of verouderde API-documenten duiden op een onbetrouwbaar product. Hoogwaardige documentatie is een direct signaal van productkwaliteit.
• Maakt zelfbediening mogelijk. Externe partners, klanten en externe ontwikkelaars kunnen integreren zonder dat je team hoeft te helpen.

API-documentatie versus gewone documentatie

In Document360 bevindt API-documentatie zich in een speciale API-werkruimte die gescheiden is van je standaard kennisbank. Dit maakt verschillende toegangscontroles, routering en branding mogelijk voor je content gericht op ontwikkelaars. Voor een volledige referentie van alle beschikbare eindpunten en schema's, zie de ontwikkelaarsdocumentatie van Document360.

Ondersteunde specificatieformaten

Document360 ondersteunt de volgende specificatieformaten:

• OpenAPI 2.0 (voorheen Swagger)
• OpenAPI 3.0
• OpenAPI 3.1 (inclusief webhook-ondersteuning)
• Postbode Collecties

Bestanden kunnen worden geüpload als JSON, YAML of YML.

Webhooks in OpenAPI 3.1

Document360 ondersteunt webhooks die zijn gedefinieerd in OpenAPI 3.1. Webhooks verschijnen met een gebeurtenispictogram in je API-referentie en bevatten een payload-sectie gebaseerd op je schema. Als er geen voorbeeld wordt gegeven, toont Document360 een standaardvoorbeeld en een voorbeeldpayload. Try It! is niet beschikbaar voor webhooks. Webhooks worden ondersteund voor bestandsuploads, URL-importen en CI/CD-flows.

Autorisatietechnieken

Bij het interacteren met een API is het belangrijk ervoor te zorgen dat alleen geautoriseerde gebruikers toegang hebben tot bepaalde gegevens of specifieke acties kunnen uitvoeren. Document360 ondersteunt de volgende autorisatiemethoden:

• Basisauthenticatie - Vereist een gebruikersnaam en wachtwoord die in het verzoek worden doorgegeven.
• Bearer token - Authenticeert met een token die na het inloggen wordt gegenereerd.
• API-sleutel - Gebruikt een unieke sleutel, doorgegeven in de requestheaders, voor authenticatie.
• OAuth2 - Beveiligt API's via verschillende stromen: autorisatiecode, PKCE, clientgegevens en impliciet.
• OpenID Connect - Uitbreidt OAuth2 door gebruikersidentiteitsverificatie toe te voegen.

Om verzoeken naar de Document360 Customer API te authenticeren, heb je een API-token nodig. Voor meer informatie, zie het artikel over API-tokens .
Om je eerste geauthenticeerde API-verzoek te doen met Swagger, Postman of curl, raadpleeg je Making your first request.

OAuth2 en OpenID Connect: aanvullende configuratie

Bij het werken met API's die OAuth2 of OpenID Connect gebruiken, zijn er twee instellingen nodig om Try It! correct te laten werken:

• Redirect URI - Stel dit in je OAuth-provider in op de OAuth-callback-URL van de API-referentie: https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html.
• Stille verlenging - Document360 verst automatisch het autorisatietoken op de achtergrond tijdens actieve Try It!-sessies, zodat gebruikers zich niet handmatig hoeven te authenticeren.

FAQ