Navegação na API públicado BIMcollab Twin

Etapa 1: Autorização

Cada solicitação à API precisa ser autenticada usando um token de acesso. Na maioria dos casos, o token de acesso será obtido usando o fluxo do código de autorização OAUTH2. Basicamente, isso significa que o usuário precisa ser redirecionado para a página de login do BIMcollab Twin a partir do seu aplicativo e será redirecionado de volta para o seu aplicativo depois que a autorização for bem-sucedida. Com o token de autorização obtido, um token de acesso pode ser solicitado. O token de acesso pode então ser adicionado ao cabeçalho "Autorização" de suas solicitações no formato: "Bearer <accesstoken>". Os tokens são fornecidos no formato JWT, portanto, quando decodificados (Base64), eles fornecem mais informações, como tempo de expiração e um ID de usuário exclusivo. Sugerimos solicitar e usar um token de atualização. Dessa forma, o usuário só precisa se autenticar no BIMcollab Twin uma vez.

Escopos disponíveis

• bimlink_publicapi - necessário para acessar a API pública do BIMcollab Twin
  
• offline_access - Necessário para usar tokens de atualização
  
• openid - Adiciona um token de ID à resposta do token
  
• email - Adiciona o e-mail do usuário ao token de ID (válido somente quando openid também é solicitado)
  

Ponto de extremidade de autorização - https://api.bimlink.nl/connect/authorize

• O URL de redirecionamento deve ser incluído na lista de permissões pelo nosso servidor de autenticação
  
• Um valor de estado pode ser fornecido para evitar falsificação de solicitação entre sites
  

Ponto de extremidade dotoken de acesso - https://api.bimlink.nl/connect/token

• O tempo de expiração está disponível no token de acesso.
  
• Contém um token de atualização quando o usuário concedeu o escopo offline_access
  

Ponto de extremidade dotoken de atualização - https://api.bimlink.nl/connect/token

• Fornece um novo token de acesso
  
• Expiração deslizante para que o tempo de vida do token de atualização seja redefinido sempre que um novo token de acesso for solicitado
  
• Deve ser solicitado em uma solicitação POST com os dados no corpo (Content-Type: application/x-www-form-urlencoded)

Os dados respondidos pelas ações são sempre específicos para o usuário atual (o usuário para o qual o token de acesso foi criado). Nunca use tokens de acesso para uma finalidade global, pois a API retorna apenas os dados que o usuário tem permissão para visualizar e, possivelmente, não o conjunto completo de dados. O escopo e as permissões de cada usuário são gerenciados no BIMcollab Twin pelo administrador da conta. Por exemplo: GET Locations para uma conta de domínio retorna apenas os locais que o usuário pode visualizar. Se a mesma solicitação for feita usando outro token de acesso que pertença a outro usuário, a resposta poderá conter dados completamente diferentes.

Etapa 2: seleção de uma conta de domínio

Todas as solicitações, exceto uma (listar as contas de domínio disponíveis para um usuário), exigem um DomainAccountId. Uma conta de domínio é uma conta corporativa e contém todos os dados de uma determinada empresa ou de um projeto muito grande. Antes de poder enviar uma solicitação de API, você terá que fornecer um menu para permitir que o usuário selecione uma conta de domínio. Sugerimos salvar a conta de domínio selecionada, pois muitos usuários usam apenas uma conta de domínio por muito tempo. Na solicitação real, a conta de domínio pode ser selecionada da seguinte forma: https://api.demo-bimlink.nl/domainaccounts/{domainAccountId}/. A ação a seguir retorna as contas de domínio disponíveis para o usuário: https: //api.bimlink.nl/swagger/index.html#/DomainAccounts/DomainAccounts_GetAll

Etapa 3: seleção de uma fase do projeto

Muitas solicitações de API também exigem um ProjectPhaseId, porque os dados de uma conta são organizados em uma estrutura de locais, projetos e fases de projeto. Portanto, para a maioria dos aplicativos, a próxima etapa após a autenticação e a seleção de uma conta de domínio será mostrar um menu de seleção de projeto, para que o usuário possa selecionar uma conta de domínio e uma fase de projeto. A ação a seguir retorna a estrutura de projeto do BIMcollab Twin para uma conta de domínio: https: //api.bimlink.nl/swagger/index.html#/Locations/Locations_GetAll

Etapa 4: Seleção de um andar

O BIMcollab Twin também oferece uma estrutura espacial para organizar os dados em uma fase do projeto. Especialmente ao solicitar dados BIM, é aconselhável permitir que o usuário selecione um andar específico criando um menu de seleção espacial. Observação: as entidades da estrutura espacial (SpatialStructureElement) não contêm dados BIM reais; para obter mais informações, consulte "Dados BIM". A ação a seguir retorna a estrutura espacial do BIMcollab Twin para uma fase do projeto: https: //api.bimlink.nl/swagger/index.html#/SpatialStructureElements/SpatialStructureElements_GetAll

Paginação

As ações GET da API em que se espera que a resposta contenha uma grande quantidade de objetos são paginadas. A paginação é controlada pelo envio de um limite (número máximo de objetos) e um deslocamento (número de objetos a serem ignorados) na string de consulta de sua solicitação. O valor máximo do limite depende da ação e pode ser encontrado na documentação do Swagger. Os metadados de paginação também podem ser encontrados nos cabeçalhos da resposta: Pagination-Limit, Pagination-Offset, Pagination-Result.