Rest API: testen en problemen oplossen

Avatar
Laura CARBO

Moeilijkheidsgraad: expert

Inhoud

Leerdoelen

Na het lezen van dit artikel kun je:

  • Workplace-API's testen

De API testen: voorbeelden

Het is mogelijk om de Workplace-API uit te proberen/te testen. Afhankelijk van de aanvraag moet je mogelijk eerst bepaalde informatie invullen.

Voorbeeld 1. De lijst met sensortoestellen ophalen

  1. Selecteer "Try it out",
  2. vervolgens "Execute",
  3. om een lijst te krijgen van alle sensortoestellen die momenteel aan deze tenant zijn gekoppeld.

Zoals je in het voorbeeld kunt zien, wordt elk sensorkanaal (bijv. luchtvochtigheid, temperatuur en CO2 in een comfortsensor) afzonderlijk geleverd.

image-20240524-135529.png

Voorbeeld 2. De huidige sensorgegevens voor een locatie ophalen

  1. Selecteer "Try it out",
  2. Voeg de verplichte locatie-ID toe
  3. vervolgens "Execute",
  4. om de huidige sensorgegevens op te halen van alle sensoren die aan die locatie zijn gekoppeld.

Zoals je in het voorbeeld kunt zien, is er 1 comfortsensor gekoppeld aan de opgevraagde locatie. Daarom worden alle voor deze sensor beschikbare kanaalwaarden (in dit geval temperatuur en luchtvochtigheid) geleverd, evenals het tijdstip waarop deze waarden zijn ontvangen.

image-20240524-135801.png

 

In de onderstaande voorbeelden wordt “locatie-ID” vermeld. Als je een locatie selecteert op https://go.cobundu.com/, wordt de referentie weergegeven, bijvoorbeeld "Meeting Room 1". In de Workplace-back-end heeft elke locatie echter een unieke locatie-ID.

Info

De locatie-ID is in de Workplace-back-end beschikbaar via de URL https://studio.cobundu.com voor elke geselecteerde locatie.

De locatie-ID voor verdieping “2nd floor” in de kantoren van Spacewell in Antwerpen is bijvoorbeeld “910000000004545”

image-20221004-082232.png

Voorbeeld 3. Reserveringen

Om de reserveringen uit je omgeving op te halen, kun je Reservations API > "get a list of bookings" gebruiken.
Wijzig de datums in de zoekinstructie om (gefilterde) reserveringen op te halen, die elk de locatie-ID bevatten en dus aangeven welke locatie is geboekt.
Voer locatie-ID's in het zoekfilter in om gefilterde gegevens op te halen.

Voorbeeld 4. Locatie-informatie ophalen

Als je een locatie selecteert op https://go.cobundu.com/, wordt de referentie weergegeven, bijvoorbeeld "Meeting Room 1". In de Workplace-back-end heeft elke locatie echter een unieke locatie-ID.


Met de Locations API kun je deze informatie ophalen.
Afhankelijk van wat nodig is:

  • een lijst met locaties voor deze klant ophalen
  • specifieke locatie-informatie opvragen (bijvoorbeeld informatie over een reeks werkplekken): "get location tree" (filter top-level results = workplace)
image-20221004-083233.png

Voorbeeld 5. Plattegrond

Om een plattegrond van Workplace op te halen, selecteer je API Locations > "get a location's drawing as SVG"
De gevraagde locatie-ID is in dit geval de verdieping-ID.
"Testing" in Swagger levert een antwoord op, maar kan de SVG niet weergeven.

Voer de locatie-ID van de verdieping in de volgende URL in om de SVG te bekijken: https://go.eu1.cloud.cobundu.com/rest/v3/locations/floor location ID/drawing/svg

image-20221004-081231.png

Voorbeeld 6. Sensorwaarden

zie REST API - GET Sensor Values

Concreet gebruiksscenario: URL om een live plattegrond weer te geven

Stel dat je een URL naar je kioskschermen wilt sturen om live plattegrondgegevens van Workplace te visualiseren.

Hier stellen we voor om een toegangstoken met een URL mee te geven, zodat iedereen met de link de live plattegrond kan bekijken.

Alternatieve methoden en veelgestelde vragen hierover vind je hier: Workplace live floorplan data visualization

 

De hieronder voorgestelde speciale methode omvat webauthenticatie via de Rest API. Dit betekent dat een gebruikersnaam en wachtwoord voor Workplace nodig zijn en dat de API een JWT-token retourneert dat kan worden gebruikt om toegang te krijgen tot alle andere API-aanroepen. Voor een autorisatiegerelateerde actie hebben we de COBUNDU Authorization-service. Deze heeft een openbare Swagger UI (en swagger.json-link) beschikbaar op https://login.cobundu.com/rest/v2/docs. Je kunt de API gebruiken via Swagger UI of Postman, of via een andere tool naar keuze. Dit voorbeeld is gebaseerd op onze Swagger UI.

Opmerking

Kies voor elke auth-gebaseerde API-methode de nieuwste versie (status september 2024: v2 is de nieuwste versie, dus raadpleeg https://login.cobundu.com/rest/v2/docs)

Vereisten

  • De webkiosk moet worden geconfigureerd in Studio
  • Per verdieping waarvoor je een visualisatie wilt instellen, is een Workplace-gebruiker nodig:

    • Workplace minimale rechten/geen specifieke rol nodig

    • rekening houdend met de reserveringsfuncties die voor deze omgeving zijn ingesteld
    • Gebruikersnaam + wachtwoord
  • Voor toegang tot de API: Workplace-gebruiker met de rol Admin of Developer

Oplossing

  1. De API gebruiken om een sessietoken op te halen

    1. Ga naar https://login.cobundu.com/rest/v2/docs (de gebruiker moet de rol Admin of Developer hebben)

      1. Selecteer "auth" > /auth/ssosettings/{loginId} (SSO-instellingen voor de gebruiker retourneren)
      2. Geef de gebruikersnaam op
      3.  De response body bevat de hostnaam van de COBUNDU Auth-instantie die moet worden gebruikt (Workplace IoT Platform is beschikbaar voor de EU en de VS) (dit kan bijvoorbeeld "apiUrl": https://login.eu1.cloud.cobundu.com zijn)
        image-20240910-073257.png

    2. Navigeer vanuit de vorige stap naar apiUrl + /rest/v2/docs, in dit voorbeeld https://login.eu1.cloud.cobundu.com/rest/v2/docs (de gebruiker moet de rol Admin of Developer hebben)

      1. Selecteer "auth" > /auth/login (gebruiker authenticeren)
      2. Geef de gebruikersnaam + het wachtwoord op die worden gebruikt om toegang te krijgen tot livegegevens
      3. Wijzig de loginparameter "rememberme": true
      4. Het overige veld kan worden verwijderd. Voorbeeld (laat bij voorkeur geen komma aan het einde van de wachtwoordregel staan): image-20240910-073146.png

         

      5.  De response body bevat accessToken
        image-20240910-073431.png

         

      6. Het toegangstoken kan worden gebruikt
  2. De URL van de webkiosk voorbereiden

    1. Ga naar http://go.cobundu.com (de gebruiker moet de rol Admin of Developer hebben) > Kiosk Mode

    2. Selecteer de relevante verdieping > open de webkiosk
    3. De URL van de webkiosk heeft de indeling https://go.cobundu.com/kiosk/MEETING%7C1d18e8b0-48a7-464c-8813-66608b474d6d
    4. Navigeer in een browser naar https://go.cobundu.com/rest/serverinfo of maak in Postman een aanvraag naar https://go.cobundu.com/rest/serverinfo?jwt= en kopieer/plak accessToken aan het einde van de URL
      image-20240910-073939.png

       

    5. De apiUrl bevat een correct cloud-eindpunt voor je account (EU of VS). Vervang go.cobundu.com in de URL van je webkiosk door deze regionale apiUrl. Je krijgt bijvoorbeeld https://go.eu1.cloud.cobundu.com/kiosk/MEETING| ...
    6. Voeg het achtervoegsel "?jwt=" toe en kopieer/plak accessToken aan het einde van de URL
    7. image-20221004-080213.png
  3. Deze URL openen (bijvoorbeeld in de incognitomodus). De webkiosk wordt geopend op de gekozen verdieping zonder om identificatie te vragen. In de applicatie wordt elke 10 minuten een sessievernieuwing uitgevoerd.

    1. Nadat het token is verkregen, heb je 10 minuten de tijd om het in de URL door te geven om de plattegrond te openen.

    2. Nadat de plattegrond is geladen, wordt het token automatisch verder vernieuwd zonder sessieverlies of handmatige tussenkomst.

       

Beperkingen

  • De webkiosk toont de reserveringsweergave (= gecombineerde bezettings- en reserveringsgegevens (indien beschikbaar))

  • Als de browser crasht/de computer wordt losgekoppeld: start het proces opnieuw om een nieuw toegangstoken te verkrijgen

 

Problemen oplossen

Probeer bij fout 401 met de volgende response body de pagina opnieuw te laden met F5

image-20241209-150441.png

 

 

 

Artikelen in deze sectie