Navigation dans l' API publique deBIMcollab Twin

Étape 1 : Autorisation

Chaque demande à l'API doit être authentifiée à l'aide d'un jeton d'accès. Dans la plupart des cas, un jeton d'accès sera obtenu en utilisant le flux de code d'autorisation OAUTH2. Fondamentalement, cela signifie que l'utilisateur doit être redirigé vers la page de connexion de BIMcollab Twin à partir de votre application et qu'il sera redirigé vers votre application une fois l'autorisation réussie. Avec le jeton d'autorisation obtenu, un jeton d'accès peut alors être demandé. Le jeton d'accès peut alors être ajouté à l'en-tête "Authorization" de vos demandes dans le format suivant : "Bearer <accesstoken>". Les jetons sont fournis au format JWT, de sorte que lorsqu'ils sont décodés (Base64), ils fournissent davantage d'informations telles que le délai d'expiration et un identifiant unique. Nous suggérons de demander et d'utiliser un jeton de rafraîchissement. De cette manière, l'utilisateur ne doit s'authentifier qu'une seule fois auprès de BIMcollab Twin.

Champs d'application disponibles

• bimlink_publicapi - Requis pour accéder à l'API publique de BIMcollab Twin
  
• offline_access - Requis pour utiliser les jetons de rafraîchissement
  
• openid - Ajoute un jeton d'identification à la réponse du jeton.
  
• email - Ajoute l'email de l'utilisateur au jeton d'identification (valable uniquement si openid est également demandé).
  

Point de terminaison d'autorisation - https://api.bimlink.nl/connect/authorize

• L'URL de redirection doit être inscrite sur la liste blanche de notre serveur d'authentification.
  
• Une valeur d'état peut être fournie pour empêcher la falsification des requêtes intersites.
  

Point de terminaison du jeton d'accès - https://api.bimlink.nl/connect/token

• La durée d'expiration est disponible dans le jeton d'accès.
  
• Contient un jeton de rafraîchissement lorsque l'utilisateur a accordé le champ d'application offline_access.
  

Point d'arrivée du jetonde rafraîchissement - https://api.bimlink.nl/connect/token

• Fournit un nouveau jeton d'accès
  
• Expiration glissante, de sorte que la durée de vie du jeton de rafraîchissement est réinitialisée chaque fois qu'un nouveau jeton d'accès est demandé.
  
• Doit être demandé dans une requête POST avec les données dans le corps (Content-Type : application/x-www-form-urlencoded)

Les données fournies par les actions sont toujours spécifiques à l'utilisateur actuel (l'utilisateur pour lequel le jeton d'accès a été créé). N'utilisez jamais de jetons d'accès dans un but global, car l'API ne renvoie que les données que l'utilisateur est autorisé à consulter, et potentiellement pas l'ensemble des données. Le champ d'application et les autorisations de chaque utilisateur sont gérés dans BIMcollab Twin par l'administrateur du compte. Par exemple, GET Locations pour un compte de domaine ne renvoie que les données que l'utilisateur est autorisé à consulter : GET Emplacements pour un compte de domaine ne renvoie que les emplacements que l'utilisateur peut visualiser. Si la même requête est effectuée à l'aide d'un autre jeton d'accès appartenant à un autre utilisateur, la réponse peut contenir des données complètement différentes.

Toutes les demandes sauf une (liste des comptes de domaine disponibles pour un utilisateur) nécessitent un DomainAccountId. Un compte de domaine est un compte d'entreprise qui contient toutes les données d'une certaine société ou d'un très grand projet. Avant de pouvoir envoyer une requête API, vous devrez d'abord fournir un menu permettant à l'utilisateur de sélectionner un compte de domaine. Nous suggérons de sauvegarder le compte de domaine sélectionné, car de nombreux utilisateurs n'utilisent qu'un seul compte de domaine pendant longtemps. Dans la demande actuelle, le compte de domaine peut être sélectionné comme suit : https://api.demo-bimlink.nl/domainaccounts/{domainAccountId}/. L'action suivante renvoie les comptes de domaine disponibles pour l'utilisateur : https://api.bimlink.nl/swagger/index.html#/DomainAccounts/DomainAccounts_GetAll

Étape 3 : Sélection d'une phase de projet

De nombreuses requêtes API nécessitent également un ProjectPhaseId, car les données d'un compte sont organisées dans une structure de lieux, de projets et de phases de projet. Ainsi, pour la plupart des applications, l'étape suivante après l'authentification et la sélection d'un compte de domaine consistera à afficher un menu de sélection de projet, afin que l'utilisateur puisse sélectionner un compte de domaine et une phase de projet. L'action suivante renvoie la structure du projet BIMcollab Twin pour un compte de domaine : https://api.bimlink.nl/swagger/index.html#/Locations/Locations_GetAll

Étape 4 : Sélection d'un étage

BIMcollab Twin fournit également une structure spatiale pour organiser les données au sein d'une phase de projet. En particulier lors de la demande de données BIM, il est conseillé de permettre à l'utilisateur de sélectionner un étage spécifique en créant un menu de sélection spatial. Remarque : les entités de la structure spatiale (SpatialStructureElement) ne contiennent pas de données BIM réelles, pour plus d'informations, voir "Données BIM". L'action suivante renvoie la structure spatiale de BIMcollab Twin pour une phase de projet : https://api.bimlink.nl/swagger/index.html#/SpatialStructureElements/SpatialStructureElements_GetAll

Pagination

Les actions API GET dont la réponse devrait contenir un grand nombre d'objets sont paginées. La pagination est contrôlée en envoyant une limite (nombre maximum d'objets) et un décalage (nombre d'objets à sauter) dans la chaîne de requête de votre demande. La valeur maximale de la limite dépend de l'action et peut être trouvée dans la documentation Swagger. Les méta-données de pagination se trouvent également dans les en-têtes de la réponse : Pagination-Limit, Pagination-Offset, Pagination-Result.