API Standard

Overview

As Trimble markets API products as part of its Connect & Scale strategy, its customers expect a unified experience of its APIs. To provide a world-class developer experience, Trimble’s APIs must follow a consistent standard. This document represents Trimble’s API standard governing all published HTTP APIs.

The Trimble API Standard is a living standard with named releases. If there is an API design element that is not covered here, you have proposed changes or additions, or need to diverge from the standard, please start a discussion with the working group for the Standard.

For more information on the goals behind the API Standard, please see Philosophy behind the Trimble API Standard.

Key Terms

Within this document, the keywords “MUST”, “MUST NOT”, “SHOULD”, “SHOULD NOT”, and “MAY” are to be interpreted as described in the table below. Note that “MUST” is not intended to convey that publishing an API may be blocked if it does not comply but that the API MUST look and behave this way if we are to achieve a cohesive, consistent experience across the whole platform catalog.

Scope

This document applies specifically to HTTP APIs. Standards for other API types, such as GraphQL, may be defined later. Interested readers should refer to the Trimble Developer Guidelines for more information.

Some Trimble APIs may need to comply with 3rd-party requirements that do not align with this Standard. APIs that need to align with other standards are expected to follow this Standard as closely as possible, with deviations documented and reviewed. Please reach out to api-standard-ug@trimble.com if deviations from the Standard are required. Furthermore, compliance with 3rd party integrations that cannot follow this Standard should be accomplished with proxy APIs that are layered on top of APIs compliant with this Standard whenever possible.

For more information on migrating existing APIs to the standard, please consult Migrating APIs to the Trimble API Standard.

API Publication Scopes

The following describes publication scopes of APIs and their meaning with respect to the compliance to this standard.

Public

Meant to be shared with anyone outside of Trimble (vendors, partners, customers, integrators, etc.)

All new APIs MUST adhere to the requirements of this document.

All existing and new APIs will be measured against it.

Furthermore, teams exposing these APIs MUST adhere to all compliance, legal, and other requirements imposed by Trimble, the integrators, and/or governmental authorities thereof. The strictest standard from the aforementioned MUST be what is used. Questions about said rules should be directed to the appropriate officers within Trimble.

Internal

Meant to be shared with others in Trimble

All new APIs MUST adhere to the requirements of this document.

All existing and new APIs will be measured against it.

Private

Exclusive to a single development team where both the client application development and server-side API development are “private” (API is not visible to other teams)

An API that exists wholly within a single product/feature domain, and is not intended to be exposed to other Trimble teams or external customers.

The domain team decides most of the parameters governing the API. Questions on requirements are left to the team and the Sector’s architecture leadership.

That being said, it is strongly encouraged that all API development follows the standard set forth herein. APIs that were once private are often eventually published. Compliance with the standard ensures an easier path to API publication.