Connect Platform

Overview

The Trimble Connect APIs allow you to read, write, and update data into and out of the Connect Platform. Now, you can create folders, upload and download files, modify views, and do much more from any application.

Terms of Service

You must agree to the Terms of Service to use Connect services.

Platform architecture

Connect Platform consists of powerful cloud-based services and cloud-enabled Trimble Connect applications for the browser, desktop and mobile.

On the client side, Connect provides Client APIs for application integrations & extensions.

On the cloud, the platform provides of a collection of Services with their corresponding APIs and SDKs.

Connect Platform is open for our customers, Trimble-internal teams & 3rd-party integrators - see Getting Started.

Client APIs

Client APIs enable application integrations with Connect applications.

Services

Connect Platform provides the following cloud-based services:

SDKs

SDKs (Software Development Kits) provide easy access to the cloud-based Connect Services.

Common Concepts

Regional Endpoints

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.

Paginated Responses

All collections/lists support a cursor or range-based mechanism to fetch partial lists (HTTP 206). See the API specifications for details.

Date Format

All dates in the API use UTC and are strings in the ISO 8601 “combined date and time representation” format.

Example `2015-05-15T15:50:38Z`

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

The service supports the following content encodings:

• deflate
• gzip
• identity

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,gzip
• Accept-Encoding:
• Accept-Encoding:*
• Accept-Encoding:deflate;q=0.5,gzip=1.0
• Accept-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.

Handling Errors

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

Error Codes (Client and Server Errors)

HTTP status codes indicate whether an operation is successful or not.

A response code of 2xx indicates that the operation was successful. Other error codes indicate either a client error (4xx) or a server error (5xx).

The error table lists the errors returned by the service. Some errors are resolved if you retry the same request. As a general rule, the timeout errors, network errors, throttling errors, and 5xx errors may be retried. The 401 error code usually indicates expired credentials and should be retried after refreshing the access token. The error table indicates which errors are likely to be resolved with successive retries. If the value of the Retry column is

• Yes - Submit the same request again.
• Yes if idempotent - Submit the same request again, but only if the given method has been implemented with idempotence.
• No - Fix the problem on the client-side before submitting a new request.

For more information about retrying requests, see Error Retries and Exponential Backoff.

Catching Errors

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-id
• X-Azure-Ref
• x-amzn-RequestId

Error Retries and Exponential Backoff

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.

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.

Support and Community

For support, visit https://community.trimble.com/community/find-answers/connect-help or reach out to connect-support@trimble.com.

Also, visit the Integrator community at https://community.trimble.com/community/find-answers/connect-help/connect-integrators.