Resource Naming

Resource URLs SHOULD identify concepts. Let the HTTP method (e.g., GET, POST, PATCH) describe the action, while the URL identifies the resource being acted upon.

The first path segment of a resource URL MUST be a noun and MUST be plural. For example, a specific Shipper resource would be retrieved using:

Example

GET /shippers/{shipperId}

Nonexample

GET /shipper/{shipperId}

Once a single resource has been identified (e.g. by including its unique ID in the URL), further path segment nouns MAY be singular.

Example

GET /people/{personId}/primaryRole

All path segments of a resource URL that represent concepts (e.g., shippers, driver, primaryRole, colors) MUST be encoded in US/American English.

Used judisciously, resource URLs MAY identify actions. When a resource URL includes a descriptive action name in its URL path, the action name MUST be the final path segment of the URL and the action MUST be invoked using a POST HTTP verb.

Example

POST /printer/{prid}/pages/{pid}/print

Nonexample

POST /print/printer/{prid}/pages/{pid}

Trimble Resource Names (TRNs)

The Standard also supports a custom URI scheme for resource identification, called Trimble Resource Names (TRNs). TRNs can be used to address resources independent of their resolvable location.

Structure

TRNs are a form of URI using a custom URI scheme, “trn.” A TRN is composed of a series of path segments separated by a colon (”:”). Path segments are not case-sensitive and must use only valid URI characters.

All path segments are mandatory.

TRN Version 1

trn:<service>:<resource-type>:<extension>

Service

The first component after the TRN scheme identifies the service or system (e.g., IAM) that created the TRN.

Resource Type

The type component of a TRN such as files has traditionally been used to identify the TRN’s service-specific data type. Resource types are assumed to be local to the Service.

The name of the resource type MUST match the name of the resource type in the url path of the resource server (or equivalent).

Extension

The final component of a TRN represents any relevant addressing information such as a service-specific identifier like k-PEcTYKNqo for the associated data within the service’s internal context. The extension supports integration with existing applications, many of which already have application-local identifiers for exposed data. This component is unrestricted for service-specific use. Trimble suggests alphanumeric local IDs that align with the service’s primary keys.

Example

trn:iam:devices:3ae6320b-fa4a-4bd1-901d-2e46ff1c3b93

TRN Version 2

Version 2 adds two new fields to the TRN: version and region.

Structure

trn:<version>:<service>:<region>:<resource-type>:<extension>

Version

Identifies the major version of the TRN format. This can be used by clients to determine how to parse the remainder of the TRN. TRN versions are meant to change infrequently (on the order of years).

Service

Identifies the service or system (e.g., IAM) that created and owns the TRN. This name must match the name of the application in IAM.

Region

Defines the physical region where the resource metadata is stored. This is relevant for data residency, compliance, and contractual requirements.

Resource Type

Identifies the TRN’s service-specific data type. For example, file, application, comment, or user. The name of the resource type MUST match the name of the resource type in the path of the resource server.

Extension

Represents the relevant addressing information for the associated data within the service’s internal context. For example, a service-specific identifier, such as a UUID.

The extension supports integration with existing applications, many of which already have application-local identifiers for their resources. This component is unrestricted for service-specific use.

Example

trn:2:fileservice:us:files:3529d0b3-5856-41ab-88b3-86f7955cddf2