CostX REST API
Getting Started Guide
Copyright © 2024 by RIB Software GmbH and its subsidiaries.
This publication is protected by copyright, and permission must be
obtained from the publisher prior to any prohibited reproduction, storage
in a retrieval system, or transmission in any form or by any means,
electronic, mechanical, photocopying, recording, or likewise.
1
Contents
1. Introduction ................................................................................................................................. 3
2. Key Information ........................................................................................................................... 3
3. Configuring the Page Size .......................................................................................................... 4
4. Using the API .............................................................................................................................. 6
4.1. Licensing ........................................................................................................................... 6
4.2. Authentication .................................................................................................................... 6
4.2.1. Creating a Personal Access Token ........................................................................ 6
4.2.2. Revoking a Personal Access Token ....................................................................... 8
4.2.3. Using a Personal Access Token ............................................................................. 9
4.3. User Permissions............................................................................................................. 11
4.4. Adding the Self-signed Certificate to “Trusted Root Certification Authorities” Store .......... 13
4.5. OData API Structure ........................................................................................................ 15
4.5.1. Using the Swagger Documentation Portal for API Discovery ................................ 16
4.5.2. Special Non-REST Public API End Point.............................................................. 19
5. Customer’s Responsibilities for Securely Using CostX API ....................................................... 20
5.1. Infrastructure Requirements............................................................................................. 20
5.2. Swagger API Portal ......................................................................................................... 20
5.3. API Endpoint Security ...................................................................................................... 21
6. Integration Considerations ........................................................................................................ 21
7. Logging ..................................................................................................................................... 21
8. Performance Considerations ..................................................................................................... 22
9. Data Warehousing Approaches ................................................................................................ 22
10. Example .................................................................................................................................... 23
2
1. Introduction
The CostX REST API provides access to data stored in CostX via public REST APIs. Most of the API
calls are OData compliant using JSON as the data payload format. The OData standard has been
chosen as this makes it easy to consume the APIs from many popular Business Intelligence, Data
Warehousing and Reporting platforms. This document provides information about the structure of the
API and how to access it. To make it easy to discover what end points are supported and how to use
them, a Swagger API discovery portal has also been implemented.
NOTES:
• Learn more about OData here: OData - the Best Way to REST
• Read more about Swagger here: About Swagger Specification | Documentation | Swagger
2. Key Information
Network
Swagger URI [Link]
e=RIB%20CostX%20API
Authorization URI [Link]
OData Service URI [Link]
OData Metadata URI [Link]
Supported OAuth2 Flows Basic - using PAT
Supported OAuth2 Scopes OData
3
3. Configuring the Page Size
This section describes how to configure the Page Size. When upgrading to a newer version, the
installer preserves the [Link] file. You can save a copy of your
[Link] file before installing an update as a precaution.
The page size can be configured using the steps below to change the number of records returned at
once. This configuration setting determines both the default page size and the maximum number of
records that can be retrieved in a single request.
1. Navigate to the C:\Program Files\Exactal\CostXODataApi\ODataService folder
and locate the [Link] file.
2. Create a copy of the [Link] file in the same folder and rename
the copied file to [Link].
3. Insert the ODataClient configuration section into the [Link] file as
shown below. You can configure the PageSize according to your need instead of the 60 as
shown here. The default value is 25 if it is not set.
4
4. Open the Windows Services Manager.
5. Select the CostX Server Core service and restart it.
5
4. Using the API
4.1. Licensing
Using the CostX REST API requires an API license in addition to the standard CostX license. For
details on how to obtain the required license, please contact our Sales team.
API licenses are activated in the same way as CostX licenses. Instructions for activating the license
will be provided along with the license.
4.2. Authentication
Authentication requires the use of a Personal Access Token (PAT).
4.2.1. Creating a Personal Access Token
The PAT is a token associated with a specific CostX user. The user can generate a PAT via the
Personal Access Token tab in CostX Options of the CostX Client.
NOTE: This feature is only available when running CostX in a Network configuration
(Client/Server system). CostX Standalone and CostX Viewer do not provide the ability to generate
a PAT.
6
To generate a PAT, click the Generate button.
The Generate personal access token dialog is displayed. Specify a display name and an expiry
date for the PAT and click OK.
NOTE: The expiry date cannot be in the past or the same as today’s date.
The token will be generated and displayed as shown below. Ensure that you copy the PAT and paste
it to a secure location where you can access it for use to access the API. The PAT cannot be displayed
again after the dialog is closed.
CAUTION: The PAT will be lost and cannot be recovered if you click OK on the above prompt
without copying the token. If that occurs, please revoke the token and generate another one.
A single user can generate more than one PAT and can have multiple PATs active at any one time.
All users are allowed to generate a PAT. However, only users with the Allow OData API Access
permission can use their tokens to access the REST API.
NOTE: When a user’s password is changed, their personal access tokens are still valid until the
expiry date. If a token needs to be revoked before expiry, follow the instructions below.
7
4.2.2. Revoking a Personal Access Token
Personal access tokens can be revoked at any time by the user.
To revoke a PAT, select it from the list and click the Revoke button. You will be prompted to choose
whether you want to remove the revoked PAT from the list.
8
4.2.3. Using a Personal Access Token
Once generated, the PAT can be used to access the REST API by using it as the password with the
HTTP Basic Authentication scheme.
For example, follow the steps below to use a PAT with the CostX OData Swagger API explorer portal:
1. Click the Authorize button located above the list of endpoints.
2. Enter your CostX username in the Username field and the PAT in the Password field.
3. Click Authorize. If the authorization succeeds, the following screen will be displayed indicating
that you are authorized.
9
4. Close the authorization dialog by clicking the Close or the X button.
CAUTION: If you navigate with only the keyboard, ensure that you tab to the Close
button before pressing Enter. By default, pressing Enter is equivalent to clicking Logout,
which will restrict you from using the API calls.
You are now authorized to call the end points from the Swagger portal using the “try it” option. See
the section Using the Swagger Documentation Portal for API Discovery for more details.
10
4.3. User Permissions
Users of the REST API must be granted the required permissions before they can access the data.
All requests to the API require the Allow OData API Access permission, which can be granted to a
user using CostX Server Admin.
NOTE: When importing or updating users in bulk from an Excel file, the Allow OData API Access
permission can be granted or restricted by adding an “Allow OData API Access” column to the
Excel file and setting it to TRUE or FLASE for individual users. This column is available in the
“Import User [Link]” file.
11
In addition to the Allow OData API Access permission, some endpoints require additional
permissions.
To view users or user permissions, the Administrator permission is required.
To view projects or anything that is contained in a project, one of the following conditions must be
met:
• The CostX user making the REST call has the Administrator permission.
• The access setting of the project is set to <Everyone> (i.e. all users can access the project).
• The CostX user is in the list of users that have access to the project (the list that shows which
users have access to the project is available in the Project Properties dialog, which can be
opened using CostX Client).
12
4.4. Adding the Self-signed Certificate to “Trusted Root Certification
Authorities” Store
By default, connections to the CostX REST API are secured with a self-signed TLS certificate that is
automatically generated during the installation of the API. As the self-signed certificate is not
universally recognized, when making calls to the API using a web browser or third-party tool, errors
like “Could not establish trust relationship for the SSL/TLS secure channel” or “Your connection is not
private” may occur.
Adding the self-signed certificate to your computer’s “Trusted Root Certification Authorities” store will
cause your computer to trust the certificate and let you make calls to the API without displaying a
security warning.
1. Navigate to the C:\ProgramData\Exactal\CostXODataApi\Certificates folder and
locate the odata_ca.cer file (the self-signed certificate shipped with CostX REST API).
NOTE: The name of the certificate file is displayed as "odata_ca" when file extensions
are hidden in Windows. The suffix ".cer" only appears at the end of the file name when you
have configured your Windows to show file extensions.
2. Right-click the certificate file and select Install Certificate.
3. The Certificate Import Wizard will start. Select Local Machine and click Next.
13
4. Select the Place all certificates in the following store option, click the Browse button to
select the Trusted Root Certification Authorities folder, and then click Next.
5. Your import settings are displayed as shown below.
6. Click Finish. A pop-up box is displayed confirming the import was successful.
14
4.5. OData API Structure
Our intention is to support the full set of API functionality via OData endpoints. This release includes
read-only OData endpoints for the following entities:
• Buildings
• Building Zones
• Code Libraries
• Codes
• Databooks
• Databook Named Cells
• Databook Sheets
• Databook Rows
• Databook Columns
• Databook Code Libraries
• Databook Codes
• Drawings
• Drawing Sets
• Dimension Groups
• Dimension Group Variables
• Dimensions
• Global Values
• Locations
• Projects
• Project Values
• Rate Libraries
• Reports
• Revisions
• Standard Variables
• Units Of Measure
• Workbooks (including Content)
• Workbook Named Cells
These are listed in the Swagger documentation which can be accessed using the link shown in the
Key Information section above.
The standard OData syntax can be used for filtering, pagination, and selecting particular fields within
each endpoint.
NOTE: $expand is currently not supported due to potential security issues.
NOTE: The entity key must be included when using the $select option against entity type.
The OData metadata endpoint provides a definition of the structure of each of the datatypes supported
by the OData API.
15
4.5.1. Using the Swagger Documentation Portal for API Discovery
The Swagger API portal can be accessed via the Swagger URI link in the Key Information section
above.
You will see a list of API entities like this:
You can expand a specific REST endpoint using the down arrow button on the right to get more
information about it. This will list the endpoints which you can again expand with the down arrow
button.
16
By default, an example JSON response is shown (as above) but you can get more detailed information
on the type of data returned by clicking on Schema.
Clicking the right arrow button next to UnitOfMeasure displays information about each field returned
for the unit of measure.
Click the […] next to a field to get a description and example of the data in the field.
17
For some fields, the meaning of the values may depend on the values in other fields, or their value
may have a special meaning as per below with rounding and default rounding.
You can try out the API against your own Data using the Try it out button in the top right.
Once you click Try it out, a blue Execute button will be displayed.
18
You can fill in any of the required parameters and click Execute to see the result.
NOTE: It is not necessary to enter any values for the 2 parameters starting with “X-”. In the
above example, you can click Execute without typing in any values and get a list of units of measure.
Other API endpoints however will require a parameter like a project key for example.
4.5.2. Special Non-REST Public API End Point
For practical reasons, a special endpoint that does not conform to OData or REST standards is
provided. This end point returns plain text (always in English) that can be used to monitor the state of
the OData service.
Health
The endpoint at “/health” provides a ping to check if the server is responding and ok.
It returns the text “Healthy” if all is ok. Any other response signifies a problem with the server.
CAUTION: This endpoint does not require authorization.
19
5. Customer’s Responsibilities for Securely Using
CostX API
5.1. Infrastructure Requirements
The various components of CostX running on premises are deemed to be running on infrastructure
that is appropriately secured by the customer’s IT administrator. For guidance on securing
infrastructure, refer to the guides published by your national cybersecurity body, such as the UK’s
Cyber Essentials scheme or the Australian Essential Eight mitigation strategies.
NOTE: It is the customer’s responsibility to prevent DoS attacks against components of CostX
running on their infrastructure.
When configuring infrastructure for CostX, customers must put appropriate measures in place to
ensure that:
• Connections between CostX Server and the Customer Application meet their reliability
requirements.
• CostX Server is running on a system that allows the Customer Application to meet its SLA
requirements.
CAUTION: Do not expose any CostX Server service ports directly to the internet. The API is
only intended for connecting CostX to the customer’s internal systems on a secured network.
5.2. Swagger API Portal
The Swagger API portal is intended to be used by the customer’s internal developers as a learning
tool for the API. The portal is not intended to be published outside of the customer's internal network
and is not intended to be used for production data flows.
By default, CostX will generate a self-signed certificate to secure traffic between Swagger and the
API. This is sufficient for most needs where access to Swagger is on an appropriately secured internal
network. It is recommended that CostX is configured to use a properly validated and trusted CA-
signed certificate to ensure TLS-secured communication between the browser using Swagger UI and
CostX. For instructions on how to use a trusted certificate with CostX, refer to the CostX Help file.
NOTE: It is the customer's responsibility to ensure that they view data in the Swagger UI in an
appropriate environment.
20
5.3. API Endpoint Security
All endpoints other than Health require authentication and authorization to access. Authentication is
done using HTTP Basic Authentication. The CostX username is passed as the username and a valid
personal access token for the user must be used as the password.
IMPORTANT: Customers are responsible for protecting their personal access tokens. If at any
time it is suspected that a token may have been wrongfully disclosed to another party, the token
should be revoked using the CostX Client application.
6. Integration Considerations
When implementing a Customer Application that integrates with the CostX API, customers are
responsible for implementing appropriate input validation and output sanitization in their application.
Data within CostX may contain special characters that need to be appropriately handled by the
application.
7. Logging
Calls to access the CostX API will result in a log entry in the CostX OData Service log.
Whenever an identifiable user makes an API call, CostX will log the call URI and the user key to the
CostX Core Server log for that call - whether it is successful or not. Customers can use this information
to monitor for potential misuse of the API. The users endpoint within the API can be used to map the
user key to a specific username.
The logs are stored on the server machine with a default location of C:\ProgramData\Exactal\Logs. It
is the responsibility of the customer to ensure that:
• The logs are secured so that they cannot be accessed by unauthorized users.
• There is enough free space on the disk for the logs. CostX does not delete or overwrite logs
and customers are responsible for setting up an appropriate schedule for archiving and
deletion of the logs.
Logging within a Customer Application is the responsibility of those developing that application.
21
8. Performance Considerations
The CostX OData API is designed to provide access to the CostX data for integration with other
systems in a convenient way. CostX data is stored in a way that is optimized for editing within CostX.
This means that data needs to be transformed for extraction. Pulling large volumes of data from CostX
using the API could be time consuming due to the work required to convert the data into a suitable
output format.
The recommended usage pattern is to periodically extract data from CostX into a corporate data lake
or data warehouse. Data will be extracted on a schedule - daily or perhaps a few times a day. You
will generally need to transform the raw data from the Cost data structures into a format suited to the
applications. This can be done by implementing custom middleware to transform the data before
inserting it into the data warehouse (ETL) or after loading it into the data lake and using tools provided
by the analytics tools being used (ELT).
To use CostX data in dashboarding, analysis, and BI tools such as Power BI, it is recommended that
customers extract and transform the data into a data warehouse first. The BI tool then connects to
the warehouse to retrieve data. This will give better performance than attempting to access data
directly from CostX via the OData API by doing the required transformation of data once.
9. Data Warehousing Approaches
There are multiple approaches that can be used to extract data from the CostX API and load it into a
data lake or data warehouse:
Example 1 - using PowerShell script: A PowerShell script can be used to extract the data from the
CostX OData API and upload it to AWS S3 or Azure Blob Storage for ingestion into your data
warehouse.
Example 2 - using MS Azure power apps: A data gateway can be configured to allow access to an
on-premises CostX server from Power Apps.
Example 3 - using AWS: AWS Glue can be configured with a Python script to extract the required
data from the CostX OData API and load it into S3.
22
10. Example
The following C# .NET 6 code can be used to display the project names. Before using, please be
aware that you will need to remove the HttpClientHandler (line 7-10) once a trusted certificate is
installed in CostX Server for connection.
using [Link];
// The default configuration use self-signed certificates. This handler disables
security functionality
// that would reject self-signed certificates. In production environments, the
server should be configured
// with a trusted certificate and this handler should be removed to ensure the
confidentiality and
// integrity of data exchanged with the CostX Server.
var handler = new HttpClientHandler()
{
ServerCertificateCustomValidationCallback =
[Link]
};
var client = new HttpClient(handler);
var plainTextBytes = [Link]("YourCostXUser:YourPAT");
string val = [Link].ToBase64String(plainTextBytes);
[Link]("Authorization", "Basic " + val);
var projectRequest = await
[Link]("[Link]
if (![Link])
{
[Link]("Failed to retrieve projects: " + [Link]);
return;
}
using var projectResponse = await [Link](await
[Link]());
var projects = [Link]("value");
foreach (var project in [Link]())
[Link]([Link]("Name"));
23
24