Navigeren door BIMcollab Twin openbare API

Stap 1: Autoriseren

Elk verzoek naar de API moet worden geauthenticeerd met behulp van een toegangstoken, in de meeste gevallen zal een toegangstoken worden verkregen door gebruik te maken van de OAUTH2 Authorization Code flow. In principe betekent dit dat de gebruiker moet worden omgeleid naar de BIMcollab Twin inlogpagina vanuit uw applicatie en wordt teruggeleid naar uw applicatie nadat de autorisatie is geslaagd. Met het verkregen autorisatietoken kan vervolgens een toegangstoken worden aangevraagd. Het toegangstoken kan dan worden toegevoegd aan de "Autorisatie" header van je verzoeken in het formaat: "Bearer <accesstoken>". Tokens worden geleverd in JWT-formaat, dus wanneer ze gedecodeerd (Base64) worden, geven ze meer informatie zoals de vervaltijd en een unieke gebruikersnaam. We raden aan om een refresh token aan te vragen en te gebruiken. Op deze manier hoeft een gebruiker zich maar één keer te authenticeren bij BIMcollab Twin.

Beschikbare scopes

• bimlink_publicapi - Vereist voor toegang tot de BIMcollab Twin Public API
  
• offline_access - Vereist om refresh tokens te gebruiken
  
• openid - Voegt een ID token toe aan de token respons
  
• email - Voegt het e-mailadres van de gebruiker toe aan het ID-token (alleen geldig wanneer ook om openid is gevraagd)
  

Autorisatie-eindpunt - https://api.demo-bimlink.nl/connect/authorize

• De redirect URL moet op de witte lijst van onze authenticatieserver staan
  
• Er kan een statuswaarde worden opgegeven om cross-site request forgery te voorkomen
  

Eindpunt toegangstoken - https://api.demo-bimlink.nl/connect/token

• De verlooptijd is beschikbaar in het toegangstoken.
  
• Bevat een ververst token wanneer de gebruiker de offline_access scope heeft toegekend
  

Eindpunt voor verversen token - https://api.demo-bimlink.nl/connect/token

• Biedt een nieuw toegangstoken
  
• Glijdende expiratie zodat de levensduur van het refresh token wordt gereset elke keer als een nieuw toegangstoken wordt aangevraagd
  
• Moet worden aangevraagd in een POST-verzoek met de gegevens in de body (Content-Type: application/x-www-form-urlencoded)

De gegevens die door de acties worden beantwoord, zijn altijd specifiek voor de huidige gebruiker (de gebruiker waarvoor het toegangstoken is aangemaakt). Gebruik toegangstokens nooit voor een globaal doel, omdat de API alleen gegevens retourneert die de gebruiker mag bekijken en mogelijk niet de volledige gegevensset. De reikwijdte en machtigingen van elke gebruiker worden beheerd in BIMcollab Twin door de accountbeheerder. Bijvoorbeeld: GET Locaties voor een domeinaccount retourneert alleen locaties die de gebruiker kan bekijken. Als hetzelfde verzoek wordt gedaan met een ander toegangstoken dat bij een andere gebruiker hoort, kan het antwoord heel andere gegevens bevatten.

Stap 2: Een domeinaccount selecteren

Alle verzoeken, behalve één (de beschikbare domeinaccounts voor een gebruiker weergeven), vereisen een DomainAccountId. Een domeinaccount is een bedrijfsaccount en bevat alle gegevens voor een bepaald bedrijf of een heel groot project. Voordat je een API-verzoek kunt verzenden, moet je eerst een menu beschikbaar stellen waarmee de gebruiker een domeinaccount kan selecteren. We raden aan om de geselecteerde domein account op te slaan, omdat veel gebruikers maar één domein account gebruiken voor een lange tijd. In het eigenlijke verzoek kan het domeinaccount als volgt worden geselecteerd: https://api.demo-bimlink.nl/domainaccounts/{domainAccountId}/. De volgende actie retourneert de beschikbare domeinaccounts voor de gebruiker: https: //api.demo-bimlink.nl/swagger/index.html#/DomainAccounts/DomainAccounts_GetAll

Stap 3: Een projectfase selecteren

Veel API-verzoeken vereisen ook een ProjectPhaseId, omdat gegevens binnen een account zijn georganiseerd in een structuur van locaties, projecten en projectfasen. Dus voor de meeste toepassingen zal de volgende stap na authenticatie en het selecteren van een domeinaccount het tonen van een projectkeuzemenu zijn, zodat de gebruiker een domeinaccount en een projectfase kan selecteren. De volgende actie geeft de BIMcollab Twin projectstructuur voor een domeinaccount: https: //api.test-bimlink.nl/swagger/index.html#/Locations/Locations_GetAll

Stap 4: Een verdieping selecteren

BIMcollab Twin biedt ook een ruimtelijke structuur om gegevens binnen een projectfase te organiseren. Vooral bij het opvragen van BIM-gegevens is het aan te raden om de gebruiker een specifieke verdieping te laten selecteren door een ruimtelijk keuzemenu aan te maken. Opmerking: de ruimtelijke structuurentiteiten (SpatialStructureElement) bevatten geen actuele BIM-gegevens, voor meer informatie zie "BIM-gegevens". De volgende actie retourneert de BIMcollab Twin ruimtelijke structuur voor een projectfase: https: //api.demo-bimlink.nl/swagger/index.html#/SpatialStructureElements/SpatialStructureElements_GetAll

Paginering

API GET-acties waarbij het antwoord naar verwachting een groot aantal objecten zal bevatten, worden gepagineerd. Pagineren wordt geregeld door een limiet (maximum aantal objecten) en een offset (aantal objecten om over te slaan) mee te sturen in de querystring van je verzoek. De maximale waarde van de limiet hangt af van de actie en kan worden gevonden in de Swagger documentatie. Paginering-metagegevens zijn ook te vinden in de headers van het antwoord: Pagination-Limit, Pagination-Offset, Pagination-Result.

BIM-gegevens

De BIM-gegevens in BIMcollab Twin worden meestal geïmporteerd uit IFC of Revit. De gegevens worden weergegeven door de volgende entiteiten:

Element

• Vertegenwoordigt een echt object
  
• Bevat (indien opgenomen)
  
  • Instellingen die specifiek zijn voor de instantie
    
  • Geometrische locatie-, verschalings- en rotatiegegevens
    
• Zoals: IfcElement
  
• Eindpunt: https://api.demo-bimlink.nl/swagger/index.html#/Elements
  

Elementtype

• Vertegenwoordigt een familie van componenten
  
• Bevat (indien opgenomen)
  
  • Instellingen die van toepassing zijn op alle componenten van dit type
    
  • Geometrische gegevens
    
  • Materialen
    
• Zoals: IfcElementType
  
• Eindpunt: https: //api.demo-bimlink.nl/swagger/index.html#/ElementTypes
  

Instellingen

• Bevat informatie over het bevattende object
  
• Zoals: IfcProperty of IfcQuantity
  
• Eindpunt: https://api.demo-bimlink.nl/swagger/index.html#/Parameters