Explanation and Concepts
Regions
Section titled “Regions”Connect API offers regional endpoints that you can use to make your requests. The resources in each region are independent of similar resources in other regions.
Regions can be discovered by calling the /regions endpoint of the master region. Use the origin field value to determine the base URL to make API calls to a specific region.
The base URLs of other regional Trimble Connect services are also returned for each region, and should always be discovered using this API. Proper use of region discovery will prevent issues if/when new Connect regions are introduced, or if the service endpoints change.
Platform Architecture
Section titled “Platform Architecture”The Connect Platform consists of powerful cloud-based services and cloud-enabled Trimble Connect applications for the browser, desktop, and mobile.
It offers two types of services:
- Client API: Allow application integrations and extensions within client-side environments.
- Cloud Services: Provide a range of cloud-based services, each with its own set of API and SDK offerings for developers.
The Connect Platform is available to our customers, Trimble internal teams, and third-party integrators. For details on how to get started, see the Access page.
Client API
Section titled “Client API”Client APIs enable application integrations with Connect applications.
| Platform | API | Description |
|---|---|---|
| Web | Workspace API | An API that enables creating Extensions for adding capabilities within the Trimble Connect for Browser application and its 3D viewer, and Embedded Connect for integration with an embedded file explorer or 3D viewer. |
| Windows | Trimble Connect for Windows API | A .NET API that allows external applications to interact with Trimble Connect for Windows |
Cloud Services
Section titled “Cloud Services”The Connect Platform provides the following cloud-based services:
| Service | Description |
|---|---|
| Core | Connect Core service allows one to read, write, and update data into and out of the Connect Platform. Now, one can create folders, upload and download files, modify views and do much more from any application |
| Model | The Model service allows you to execute queries over Building Information Models (BIM). |
| Model Feature | The Model Feature service provides read access to Organizer groups in Connect projects. |
| Organizer | The Organizer service allows one to manage hierarchical breakdown structures. |
| Property Set | The Property Set service allows one to manage libraries of property set definitions and attach property sets to external objects. |
| Topics | BCF 2.1 compatible service for managing issues on a Connect project. |
Software Development Kits provide easy access to the cloud-based Connect Services.
| Platform | SDK | Server APIs covered |
|---|---|---|
| Windows / .NET | Trimble Connect .NET SDK (NuGet) | API client, local data management/sync for: Core, Organizer, Property Set |
| Web / JavaScript, TypeScript | trimble-connect-sdk (npm) | API client for: Core, Organizer, Property Set |
Technical details
Section titled “Technical details”Paginated Responses
Section titled “Paginated Responses”All collections/lists support a cursor or range-based mechanism to fetch partial lists (HTTP 206). See the API specifications for details.
Cross-Origin Resource Sharing
Section titled “Cross-Origin Resource Sharing”This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with the W3C spec that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.
Payload Compression
Section titled “Payload Compression”The service supports the following content encodings:
deflategzipidentity
The service accepts compressed request payloads. The Content-Encoding header must be sent in the request to decode the request payload properly.
For responses, the compression is applied automatically for responses larger than 1KB.
The compression method can be negotiated with the Accept-Encoding header.
The following Accept-Encoding header formats, according to the RFC 7231 specification, are supported:
Accept-Encoding:deflate,gzipAccept-Encoding:Accept-Encoding:*Accept-Encoding:deflate;q=0.5,gzip=1.0Accept-Encoding:gzip;q=1.0,identity;q=0.5,*;q=0
If the header is not set, the default value is * as defined in RFC 7231. In such cases, the payload is not compressed.
Errors
Section titled “Errors”Handling
Section titled “Handling”The response body for all error responses are in the same format and include the error code and message.
When you send requests to and get responses from the Service API, you might encounter two types of API errors
- Client errors - Client errors are indicated by a 4xx HTTP response code. Client errors indicate that the service found a problem with the client request. This can include such things as an authentication failure or missing required parameters. Fix the issue in the client application before submitting the request again.
- Server errors - Server errors are indicated by a 5xx HTTP response code and need to be resolved by Trimble. You may resubmit/retry the request until it succeeds.
For each API error, the API Gateway returns the following values
- A status code, for example,
400 - An error code, for example,
ValidationException - An error message, for example,
Supplied AttributeValue is empty, must contain exactly one of the supported data types
Catching
Section titled “Catching”For your application to run smoothly, you need to build in logic to catch and respond to errors. One typical approach is to implement your request within a try block or if-then statement.
The client-side SDKs perform retries and error checking. If you encounter an error while using one of the SDKs, you should see the error code and description. To help troubleshoot any issues with Trimble Connect support, you should also check the value of any of the following headers
tc-request-idX-Azure-Refx-amzn-RequestId
Retrying
Section titled “Retrying”Numerous components on a network, such as DNS servers, switches, load balancers, and others can generate errors anywhere in the life of a given request.
The usual technique for dealing with these error responses in a networked environment is to implement retries in the client application. This technique increases the reliability of the application and reduces operational costs for the developer.
Official Trimble Connect SDKs implement automatic retry logic. There is also configuration available to change the retry settings.
If you’re not using the official SDKs, you should retry original requests that receive server errors (5xx). However, client errors (4xx, other than a TooManyRequestsException) indicate you need to revise the request itself to correct the problem before trying again.
Exponential Backoff
Section titled “Exponential Backoff”In addition to simple retries, it is recommended to use an exponential backoff algorithm for better flow control. The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. For example, you might let one second elapse before the first retry, four seconds before the second retry, 16 seconds before the third retry, and so on. However, if the request has not succeeded after a minute, the problem might be a hard limit and not the request rate. For example, you may have reached the maximum number of pipelines allowed. Set the maximum number of retries to stop around one minute.