Troubleshooting

API Performance

Quick triage checklist

• Version: Confirm ART.exe version; consider upgrading TruckMate if not current as performance improvements have been made to newer versions.
• Server health: Uptime, CPU, RAM, disk, and recent reboots (target ≤30 days).
• Database: RUNSTATS/REBIND, investigate slow SQL, confirm package binds.
• Logs: Identify slow endpoints in ART service logs; capture request IDs and durations.
• Request shape: Minimize payloads (filters, fields, paging).
• Network: Validate firewall, TLS inspection, and latency between app and DB.

Paging, payload size, and expand

REST performs best with many small, fast requests rather than a few very large ones. Large responses amplify DB work, JSON serialization, and network transfer, increasing latency and tying up API threads and DB connections—under load this can slow unrelated calls and even destabilize the service.

• Paging
  • All GETs default to limit=20. Always set an explicit small limit (e.g., 20–50) and iterate pages.
  • Example:

GET /tm/orders?limit=20

• Impact of large result sets

  • Bigger pages increase DB scan/join time, JSON serialization, and bytes-on-the-wire—often superlinearly with complex joins.
  • Repeated large queries can exhaust thread/connection pools and trigger timeouts; at scale, they can push the API and DB into sustained overload.

• Expand

  • Each expand adds joins and nested data, multiplying cost with page size.
  • Prefer a two-step pattern: fetch a small list, then fetch details by id; or keep expand but lower limit substantially.
  • Examples:

# Large payload (avoid unless necessary)
GET /tm/orders?expand=details,traceNumbers

# Constrained list
GET /tm/orders?limit=20

# Single resource
GET /tm/orders/{orderId}

# Minimal expand with limit
GET /tm/orders?limit=20&expand=details

Connection Problems

There maybe connection problems from the client app to the ART Server. Here are some of the items to check for.

• Check the ART Server is not conflicting with another TCP port. For example a common web port is 80. But another service like Apache or IIS may already be using that port. ART Server will need to be configured to listen on a different port.
• Check the firewall. The client application maybe going through the internet and then the firewall to connect to the Art Server. Make sure the firewall is configured to redirect the web requests to the specific IP address running the ART Server. Some firewalls use NAT to redirect the web requests to the ART Server.
• Check for virus scanner software. Virus scanners today are more than just checking files on the computer for viruses. They also check the internet traffic to see if there is any kind of hacking activity. Try temporarily disabling the virus scanner and retry the web requests.

To check if the ART server is running navigate to the /version endpoint. To check the that the ART Server is connected to the DB2 database, navigate to the /whoami endpoint. For a successful response pass a valid API Key Bearer Token in the request header.