Navigate the API with Links

Overview

This API supports RESTful link navigation, meaning that a client can explore the data without needing to know or plug in any IDs. Much like a human user clicking through a website, it simply uses the links that it is given to retrieve the next page of related data.

See the API Explorer in this documentation site for a working example of this style of navigation.

Example

When making requests to the API, each response is a representation of one or more resources. Each representation includes a links block, containing URLs that link to related resources.

For example, a Device representation looks like:

 {
    "id": "trn::profilex:us-west-2:device:78074e07-997e-414a-9a3f-cc7113c5d77d",
    "name": "Tablet-TABLET-SITENAV-PHONE",
    "appName": "SiteNavigator",
    "associatedMachineId": "trn::profilex:us-west-2:device:78074e07-997e-414a-9a3f-cc7113c5d77d",
    "links": {
        "self": {
            "rel": "self",
            "href": "https://localhost:7024/projects/trn::profilex:us-west-2:project:08606a33-2e3a-4d9e-bacf-50750a51e046/devices/trn::profilex:us-west-2:device:78074e07-997e-414a-9a3f-cc7113c5d77d"
        },
        "machine": {
            "rel": "machine",
            "href": "https://localhost:7024/projects/trn::profilex:us-west-2:project:08606a33-2e3a-4d9e-bacf-50750a51e046/machines/trn::profilex:us-west-2:device:78074e07-997e-414a-9a3f-cc7113c5d77d"
        },
        "designs": {
            "rel": "designs",
            "href": "https://localhost:7024/projects/trn::profilex:us-west-2:project:08606a33-2e3a-4d9e-bacf-50750a51e046/devices/trn::profilex:us-west-2:device:78074e07-997e-414a-9a3f-cc7113c5d77d/designs"
        },
        "coordinates": {
            "rel": "coordinates",
            "title": "current",
            "href": "https://localhost:7024/devices/trn::profilex:us-west-2:device:78074e07-997e-414a-9a3f-cc7113c5d77d/coordinates"
        }
    }
}

From this response, we can see a few things:

1. A self link, where href is a reference to the current resource. In practice, this acts as a unique identifier for this resource.
2. A machine link, where href points to the machine that this device is attached to.
3. A designs link, where href points to the list of designs that have been assigned to this device.
4. A coordinates link. With a title of current, we can determine that href points to the current location of the device.

Getting Started

To begin making requests, a home resource is provided at GET /, which looks like:

{
    "links": {
        "self": {
            "rel": "self",
            "href": "https://localhost:7024/"
        },
        "accounts": {
            "rel": "accounts",
            "href": "https://localhost:7024/accounts"
        },
        "projects": {
            "rel": "projects",
            "href": "https://localhost:7024/projects"
        }
    }
}

By following the links to your accounts or projects, you can continue from where the other tutorials start. Notice that every time you could find an ID and construct a URL, there is a link already provided in the response.

AI Tooling

Many AI agents are very proficient at navigating APIs in this manner. They need:

• a web request tool, like curl
• to be told how to authenticate. For example, by providing the authentication token in a text file that the AI tool can access.

An example prompt to gather device locations could look like the following:

Explore the API exposed at https://cloud.api.trimble.com/site-management/v1/ by using the links it provides.
Use the JWT in ./my-token.txt as a Bearer token to authenticate.
Tell me what devices are on each project and draw their locations on a map