Get Started
Prerequisites
Section titled “Prerequisites”The APIs require an existing TruckMate installation and are licensed separately.
Similar to TruckMate, the API Server is either self-hosted or hosted as a single-tenant solution by Trimble Transportation. Please see the Getting Started page for API server set-up instructions.
Best Practices for Building Reliable REST Integrations
Section titled “Best Practices for Building Reliable REST Integrations”Building a new integration using REST APIs requires more than simply wiring up endpoints. A well-designed integration must be reliable, scalable, maintainable, and resilient to failure. Following established REST best practices ensures systems remain performant under load, easy to evolve, and operationally stable.
This article outlines key principles and practical guidance for building high-quality REST integrations.
Keep Requests Small, Fast, and Purposeful
Section titled “Keep Requests Small, Fast, and Purposeful”Large payloads, excessive query limits, and broad data fetches are common causes of degraded performance.
Best practices:
Section titled “Best practices:”- Request only the fields you actually need.
- Use pagination instead of large result sets.
- Avoid large limit values that return thousands of records per call.
- Prefer multiple small requests over fewer, extremely large ones.
Why it matters:
Section titled “Why it matters:”Small, fast requests reduce server load, improve responsiveness, and protect system stability under sustained traffic.
Use Pagination and Filtering Correctly
Section titled “Use Pagination and Filtering Correctly”APIs should never require clients to retrieve entire datasets.
Best practices:
Section titled “Best practices:”- Always implement pagination for list endpoints.
- Use filtering and query parameters to reduce result sizes.
- Support incremental data access patterns (e.g., timestamps).
Why it matters:
Section titled “Why it matters:”Efficient pagination prevents excessive memory usage, slow responses, and cascading failures.
Implement Backoff and Retries
Section titled “Implement Backoff and Retries”Transient failures are normal in distributed systems. Integrations must be resilient, not brittle.
Best practices:
Section titled “Best practices:”- Use exponential backoff for retries.
- Avoid aggressive retry loops.
Treat 429 (Too Many Requests) and 5xx responses as signals to slow down.
Why it matters:
Section titled “Why it matters:”Smart retry logic prevents retry storms that amplify outages and protects both client and server stability.
Test Beyond the Happy Path
Section titled “Test Beyond the Happy Path”Functional success alone is not sufficient.
Best practices:
Section titled “Best practices:”- Perform load and stress testing.
Why it matters:
Section titled “Why it matters:”Testing failure modes ensures predictable behavior under real-world conditions.
Summary
Section titled “Summary”Strong REST integrations are built on small requests, stateless design, resilience and disciplined API contracts. Systems that follow these principles scale predictably, recover gracefully, and remain stable even under sustained load.
When integrations violate these practices—especially by issuing repeated, large, high-cost requests—they introduce significant risk to platform stability and reliability.
Designing thoughtfully from the start avoids operational incidents, improves performance, and lowers long-term maintenance costs.
URL and License
Section titled “URL and License”| API Service | License Key | Base URL | Description |
|---|---|---|---|
| TruckMate REST API | 69000 | /tm | A comprehensive set of endpoints and methods, allowing transactional integration with major TruckMate product areas. |
| Master Data | 69001 | /masterData | Allows external systems to create, retrieve, update or delete TruckMate configuration data. |
| Finance API | 69200 | /finance | Allows external systems to create, retrieve, or update Truckmate financial information such as invoices, payments, GL entries, and more. (Available in version 2024.3 and later.) |
Authentication
Section titled “Authentication”When using the TruckMate REST APIs the calling application must pass along a Bearer Token to prove their identity to the On-Premise API server. Bearer Tokens are the predominant type of access token used with OAuth 2.0. A Bearer Token must be set in the Authorization header of every request.
TruckMate REST APIs offer 2 methods for authentication.
- TruckMate API Key generated in one of TruckMate’s Window applications
- Login endpoint to generate a time sensitive JWT token
Authorization
Section titled “Authorization”TruckMate REST APIs offer 5 methods of authorization which allow varying access to endpoints and data
- TruckMate User API Key generated within the Security Configuration application on the TruckMate API Credentials tab.
- Login endpoint to generate a time sensitive JWT token
- Client API Key
- Vendor API Key
- TID