Moeilijkheidsgraad: expert
Inhoud
Leerdoelen
Na het lezen van dit artikel kun je:
- begrijpen wat Workplace API's kunnen doen
- Workplace API's testen
API staat voor Application Programming Interface en maakt het eenvoudig om gegevens en functionaliteit uit te wisselen. De documentatie van de Workplace API (Swagger) is beschikbaar in een apart tabblad in het GO-menu.
Toegang tot de Workplace API
- Ga naar https://go.cobundu.com/
- Log in met je inloggegevens
Het menu-item “API” verschijnt alleen voor gebruikers aan wie de rol van ontwikkelaar of beheerder is toegewezen. Zie Rollen en profielen voor meer informatie.
De Workplace API gebruiken
Een server-sideoplossing gebruiken
Hoewel het een goed idee is om vertrouwd te raken met de Workplace API door via een browser toegang te krijgen tot de GO-omgeving van je tenant, wordt het afgeraden om een browsergebaseerde aanpak te gebruiken om onze API's te integreren en gegevens uit Workplace naar een database van een derde partij te halen. De API moet servergebaseerd worden gebruikt.
Door verzoeken te versturen vanuit een beveiligde back-end:
- Omzeil je de CORS-beperkingen van de browser.
- Houd je meer controle over gegevensverwerking en authenticatie.
- Verminder je potentiële beveiligingsrisico's aanzienlijk.
- Verbeter je de prestaties en schaalbaarheid.
Als SaaS-provider staan we om veiligheidsredenen het insluiten in de browser vanuit andere origins met domeinen van derden niet toe. Als het uiteindelijke doel is om de sensorgegevens op te halen en in een database in te voegen, raden we sterk aan een server-sideoplossing te bouwen.
Genummerde API-versies gebruiken om conflicten te voorkomen
Als je de API's in je eigen projecten wilt gebruiken (bijv. Postman), kun je geïnteresseerd zijn in het gebruik van de swagger.json-link. Zoals je in de bovenstaande schermafbeelding kunt zien, wordt standaard de pagina "latest" geopend, maar dit kan natuurlijk veranderen.
Opmerking
Gebruik genummerde versies (bijv. https://go.cobundu.com/rest/v3/docs) om conflicten te voorkomen.
Het gebruik van een specifieke versie heeft als voordeel dat je API-versies in de toekomst kunt vergelijken.
Opmerking
Zorg ervoor dat je voor elke API-methode de nieuwste versie kiest
Status september 2024
- GO API: v3 is de nieuwste versie, dus gebruik https://go.cobundu.com/rest/v3/docs
- auth-based API: v2 is de nieuwste versie, dus gebruik https://login.cobundu.com/rest/v2/docs
Het serverantwoord interpreteren
Valideer de verzoekparameters in de Workplace API Try It Out-GUI. Het antwoord in de GUI bevestigt dat de parameters correct zijn door een 200-code en waarden te verstrekken.
Toch is alleen een 200-code niet voldoende. Deze bevestigt dat de parameters correct zijn, maar er kan nog steeds een probleem zijn:
Code 200 - Response body leeg ([])
Als de datum From bijvoorbeeld in de toekomst ligt, is de response body leeg
De Request URL uit "API Try it Out" gebruiken om je resultaat te valideren
Om te bevestigen dat het antwoord op de Request URL uit "API Try it Out" werkt, kun je deze gewoon in je browser plakken (dit werkt alleen voor een beperkt aantal methoden, namelijk methoden die de GET-methode gebruiken).
Info
Zorg ervoor dat je in dezelfde browser bent ingelogd bij Workplace (oftewel dat er een actieve Workplace-sessie is geopend) voordat je de URL in de adresbalk plakt om de resultaten te kunnen zien.
Postman of een andere tool die je gebruikt, moet exact dezelfde URL weergeven als de Request URL die zichtbaar is in het antwoord van Workplace API Try It Out. Het pipe-teken moet bijvoorbeeld op een bepaalde manier worden gedecodeerd in Postman. Bekijk https://en.wikipedia.org/wiki/Percent-encoding voor meer informatie over de juiste codering van speciale tekens.