Appendix

Standard Release Strategy

The Trimble API Standard follows a modified calendar versioning scheme of the form RYYYY.N where

YYYY is the full year of the release
N is an incremental release number

Example: R2023.3 represents the third standards release of 2023.

All releases published and archived to the API Standards Repository.

Philosophy behind the Trimble API Standard

Trimble is striving to provide a catalog of industry-leading APIs supported by a world-class developer experience. Trimble’s developer experience will be driven by ease of adoption derived from APIs that are consistent and cohesive both within and across its APIs. Achieving this consistency and cohesion requires a standard to which to align our APIs, and this is that Standard.

The intention of this standard was not to create a standard that was perfect or state-of-the-art, but one that provides the Trimble way of creating a consistent API experience for developers inside and outside Trimble. There may be better ways of implementing many of the standards, and there are certainly alternatives. However, the Standard’s working group has settled on the standard listed here, and is committed to its growth and evolution as Trimble builds a deeper API ecosystem.

This living standard is the foundation of our future API ecosystem, and the group working on the API Standard looks forward to growing it with your participation.

Migrating APIs to the Trimble API Standard

It is recognized that not all APIs currently deployed follow this standard. These include legacy APIs as well as those developed with very specific considerations and constraints. We anticipate convergence to and eventual compliance with this Standard as part of the Connect and Scale initiative.

Additionally, private APIs MAY NOT conform to this Standard. However, this is strongly recommended to make them easily usable by wider Trimble teams.

Background on Time Ranges

This standard specifies time ranges with the start time inclusive and end time exclusive due to several issues that can happen with end time inclusive ranges:

Inclusive end times force clients to specify the end time with high decimal precision hoping that they have used enough precision to get all events for the period. For example, a range of events from 00:00:00 to 23:59:59 would not include an event that occurred at 23:59:59.5. No matter how precise (e.g. 23:59:59.999), there would be a chance of missing events.
Exclusive end times also make it easier to implement rolling time windows since the end time of the range (regardless of the length of the range) can simply be used as the beginning of the next range without the risk of capturing data twice if a data item happens to exist at a range boundary.

In addition, this standard favors this ISO-8601 time range format over the oft-used separate “start time” and “end time” fields/parameters to emphasize official standards conformance.

Stable Sorts

Implementations of sorting benefit from consistent ordering of items whose sort parameters are equivalent (e.g. 2 records with the same time stamp). This requires choosing one or more resource attributes that, when taken together, provide a unique, sequential identifier for the resource within the collection. This ensures the resource collection always has a unique, linear ordering with respect to this identifier. Examples of possible such identifiers include:

Event timestamp combined with “Received Time” It is possible that 2 events can occur at the same time (“event time”) but it is impossible for 2 event data packets to arrive into the server at exactly the same time (“received time”). In the case of sorting by event time, the received time can be used as a secondary sort parameter that is used when the event times of 2 or more records are equivalent to ensure the sort order is stable.
People’s names combined with employee ID Similar to event timestamp, it is possible for 2 people to have the same name so using an attribute such as employee id as the secondary sort parameter ensures a stable and repeatable sort order.

Use of JSON as Trimble’s common data interchange format for APIs

A consistent developer experience requires a common data interchange format. JSON was chosen as this common format due to the following features:

Popularity with API developers
Readability
Flexibility

Other data interchange formats may be used where appropriate for the target consumers.

Request Response Clarity

Clear, consistent error messages are a critical feature of good API products and are important pieces of a world-class developer experience. Error messages are critical at all phases of the API integration lifecycle:

Exploration: Quickly finding issues during POCs, which builds trust in the API
Integration: Rapid debugging of issues during integration, and building solid client-side error handling.
Production: Fast triage and resolution of production issues.

Error message clarity is especially important for 400, 404, 405, and 5xx errors, as those errors often require code changes or operational responses. Please ensure that all of these errors have unambiguous explanations with at least one suggested method for correcting the error.

It is recommended that error messages are vetted by non-technical personnel, such as technical writers, product managers, and sales engineers for clarity and readability.

Trimble-Specific Media Types

There are currently no known Trimble-specific media types.