Navegación por la API pública de  BIMcollab Twin

Paso 1: Autorización

Cada petición a la API necesita ser autenticada usando un token de acceso, en la mayoría de los casos un token de acceso se obtendrá usando el flujo de código de autorización OAUTH2 . Básicamente, esto significa que el usuario necesita ser redirigido a la página de inicio de sesión de BIMcollab Twin desde tu aplicación y será redirigido de nuevo a tu aplicación después de que la autorización haya sido satisfactoria. Con el token de autorización obtenido se puede solicitar un token de acceso. El token de acceso se puede añadir a la cabecera "Autorización" de sus solicitudes en el formato: "Bearer <accesstoken>". Los tokens se proporcionan en formato JWT , por lo que cuando se descodifican (Base64) proporcionan más información, como el tiempo de caducidad y un identificador de usuario único. Sugerimos solicitar y utilizar un token de actualización. De esta forma el usuario sólo tiene que autenticarse con BIMcollab Twin una vez.

Ámbitos disponibles

• bimlink_publicapi - Necesario para acceder a la API pública de BIMcollab Twin
  
• offline_access - Necesario para usar tokens de actualización
  
• openid - Añade un token ID a la respuesta del token
  
• email - Añade el correo electrónico del usuario al token de ID (sólo válido cuando también se solicita openid)
  

Punto final de autorización - https://api.bimlink.nl/connect/authorize

• La URL de redirección debe estar en la lista blanca de nuestro servidor de autenticación.
  
• Se puede proporcionar un valor de estado para evitar la falsificación de solicitudes entre sitios.
  

Punto final de token de acceso - https://api.bimlink.nl/connect/token

• El tiempo de caducidad está disponible en el token de acceso.
  
• Contiene un token de actualización cuando el usuario concede el ámbito offline_access
  

Punto final del token de actualización - https://api.bimlink.nl/connect/token

• Proporciona un nuevo token de acceso
  
• Expiración deslizante, de modo que la vida útil del token de actualización se restablece cada vez que se solicita un nuevo token de acceso.
  
• Debe solicitarse en una petición POST con los datos en el cuerpo (Content-Type: application/x-www-form-urlencoded)

Los datos respondidos por las acciones son siempre específicos para el usuario actual (el usuario para el que se creó el token de acceso). Nunca utilice tokens de acceso para un propósito global porque la API devuelve sólo los datos que el usuario está autorizado a ver y potencialmente no el grupo completo de datos. El alcance y los permisos de cada usuario son gestionados en BIMcollab Twin por el administrador de la cuenta. Por ejemplo: GET Ubicaciones para una cuenta de dominio sólo devuelve las ubicaciones que el usuario puede ver. Si la misma petición se realiza utilizando otro token de acceso que pertenece a otro usuario la respuesta puede contener datos completamente diferentes.

Paso 2: Selección de una cuenta de dominio

Todas las peticiones excepto una (listar las cuentas de dominio disponibles para un usuario) requieren un DomainAccountId. Una cuenta de dominio es una cuenta corporativa y contiene todos los datos de una empresa determinada o de un proyecto muy grande. Antes de poder enviar una solicitud API, primero tendrá que proporcionar un menú que permita al usuario seleccionar una cuenta de dominio. Le sugerimos que guarde la cuenta de dominio seleccionada, ya que muchos usuarios sólo utilizan una cuenta de dominio durante mucho tiempo. En la solicitud real, la cuenta de dominio puede seleccionarse de la siguiente forma: https://api.demo-bimlink.nl/domainaccounts/{domainAccountId}/. La siguiente acción devuelve las cuentas de dominio disponibles para el usuario: https: //api.bimlink.nl/swagger/index.html#/DomainAccounts/DomainAccounts_GetAll

Paso 3: Selección de una fase del proyecto

Muchas solicitudes de API también requieren un ProjectPhaseId, porque los datos de una cuenta se organizan en una estructura de ubicaciones, proyectos y fases de proyecto. Por tanto, para la mayoría de las aplicaciones, el siguiente paso tras la autenticación y la selección de una cuenta de dominio será mostrar un menú de selección de proyectos, para que el usuario pueda seleccionar una cuenta de dominio y una fase de proyecto. La siguiente acción devuelve la estructura del proyecto BIMcollab Twin para una cuenta de dominio: https: //api.bimlink.nl/swagger/index.html#/Locations/Locations_GetAll

Paso 4: Seleccionar una planta

BIMcollab Twin también proporciona una estructura espacial para organizar los datos dentro de una fase de proyecto. Especialmente cuando se solicitan datos BIM, se recomienda permitir al usuario seleccionar una planta específica creando un menú de selección espacial. Nota: las entidades de estructura espacial (SpatialStructureElement) no contienen datos BIM reales, para más información consulte "Datos BIM". La siguiente acción devuelve la estructura espacial de BIMcollab Twin para una fase del proyecto: https: //api.bimlink.nl/swagger/index.html#/SpatialStructureElements/SpatialStructureElements_GetAll

Paginación

Las acciones GET de la API en las que se espera que la respuesta contenga una gran cantidad de objetos se paginan. La paginación se controla enviando un límite (número máximo de objetos) y un offset (número de objetos a omitir) en la cadena de consulta de la solicitud. El valor máximo del límite depende de la acción y puede consultarse en la documentación de Swagger. Los metadatos de paginación también se encuentran en las cabeceras de la respuesta: Pagination-Limit, Pagination-Offset, Pagination-Result.