REST API

Data Sources

This topic has the following sections:

Example Uses

As a system integrator, I need to be able to export from Archibus up-to-date building information for one or several buildings, in order use it in external systems such as GIS systems, capital planning systems, and so on.

When getting building information from Archibus, I need to be able query a sub-set of buildings by applying filters, in order to:

  • Get all the buildings in the Archibus inventory.
  • Export only the building inventory that I am using in the external system, by specifying the list of building codes or geographical region
  • Filter by building status. For example, filter out disposed buildings (such as sold, demolished)
  • Get only buildings for which the Building’s field values (from bl table) that the API exposes, have changed since the last export
  • Export only the buildings for the sites that we are using in the external systems.

API

This API provides access to data via a data source. The client specifies the data source name.

Integration APIs benefit from using data sources, which can handle tasks such as:

  • encapsulate data access details
  • join multiple data tables
  • apply complex restrictions
  • support auto-lookup for numeric ID.

Security Permissions

The Data REST API accesses Archibus database only via data sources. The API respects Archibus data security, including per-user and per-role VPAs and per-field security groups.

REST API user role

All REST APIs impersonate a user with a role configured in /WEB-INF/config/oidc.propertie s:

oidc.role=4 - API USER

By default, in the schema and HQ databases, this role is defined with:

  • Same security groups as the 4 - PROCESS OWNER - MODULES (ACP) role.

  • No VPA.

Secure tables

Archibus allows access to secure tables and fields (e.g. afm_users) only to users with the SYS-USRMGR security group. The REST API user role should not be assigned this security group.

Fine-grained access control

Customers can configure REST API access control for specific data fields.

Example Steps
REST API should have the same read-write access to space inventory as interactive users.
  • Assign SPAC-REV-ED and, optionally, RPLM-REV-ED security groups to the 4 - API USER role.

REST API should have read-only access to space inventory.

  • Assign SPAC-REV and, optionally, RPLM-REV security groups to the 4 - API USER role.
REST API should have read-write access to some space inventory fields.

  • Create security group SPEC-REV-API.

  • Assign the SPAC-REV-API group to the 4 - API USER role.

  • Change “review” and “edit” security groups for specific fields from SPEC-REV and SPAC-REV-ED to SPEC-REV% and SPAC-REV-ED%. These fields will be accessible both to REST API and to interactive users.

Data Sources

The data API loads data sources from / schema/ab-products/common/api/ab-api-datasources.axvw .

Data source name should follow this convention:

Api_[ dataSourceName ]_v[ version ]

  • version is a version of the data source. The first implementation of the data source has version = 1. Each change to the data source implementation that’s not backwards-compatible increments the version.

  • dataSourceName is a descriptive name of the data source.

Example:

  • Api_HrEmLocations_v1 (initial version)

  • Api_HrEmLocation s_v2 (version 2 which provides additional functionality and changes the data format)