EnduranceTrio Tracker REST API

Table of Contents

1. Introduction
2. Features
   1. Core Functionality
   2. API Endpoints
   3. Swagger UI & API Documentation
3. Development
   1. Technology Stack
   2. API Key Management
   3. Database
   4. Installation
   5. Code & Naming Conventions
   6. Programmatic Version Management
4. Deployment
   1. Container Architecture
   2. Server Setup
   3. Reverse Proxy Setup
   4. SSL Certificate
5. License

Introduction

EnduranceTrio Tracker is a modern REST API designed for managing IoT device telemetry. Built with Java 21 and Spring Boot 4, the service provides a scalable and secure solution for submitting and retrieving devices telemetry data using API key authentication. It is ideal for applications such as fleet management, asset tracking, and general IoT device monitoring.

Development Team

This project was created by Ricardo do Canto, who is the lead developer and maintainer.

Features

Core Functionality

• Secure Telemetry Submission: Submit device telemetry data with API key authentication
• Device Telemetry Retrieval: Get the last known telemetry for all existing devices
• Telemetry History: Access historical telemetry data for comprehensive tracking and analysis
• Auto-generated Documentation: Interactive API documentation via Swagger UI

API Endpoints

The following table summarizes the available endpoints.

Method	Endpoint	Description	Authentication
GET	/tracker/v1/devices	Get last known telemetry for all existing devices	API Key Required
POST	/tracker/v1/devices	Submit a device telemetry data point	API Key Required
GET	/tracker/v1/devices/{device}/telemetry	Get historical telemetry for a device (supports pagination)	API Key Required
GET	/tracker/v1/routes	Get all route configurations	API Key Required
POST	/tracker/v1/routes	Submit a route configuration	API Key Required
GET	/tracker/v1/routes/({id}	Find route configuration by id	API Key Required
GET	/tracker/v1/routes/({id}/metrics	Retrieves the GeoJSON definition for a specific route	API Key Required

For comprehensive documentation including request/response schemas, examples, and error handling, see the following documents:

• Tracker Domain

Swagger UI & API Documentation

The EnduranceTrio Tracker API provides interactive documentation through Swagger UI, with separate documentation groups for different environments. This graphic interface allows you to:

• Explore all available endpoints within the Tracker domain.
• View request/response models (e.g., DeviceTelemetryDTO).
• Test API calls directly from your browser.

Environment-Specific Access

The Swagger UI endpoint varies by environment and deployment configuration:

Environment	Default URL	Note
Local Development	http://localhost:8081/swagger-ui.html	Direct application access
Public	openapi subdomain	Configured via Apache proxy

Selecting the Correct Environment Group

When you access Swagger UI, you must select the appropriate documentation group for your environment:

1. Look for the dropdown menu in the top-right corner of the Swagger UI page (labeled with the current group name)
2. Choose the correct group based on your environment:
   • Tracker Domain (LOCAL) - For local development (uses paths with /api prefix)
   • Tracker Domain (PROD) - For production use (uses paths without /api prefix)

Important: When accessing Swagger UI through the openapi subdomain in production, the gateway strips the /api prefix from paths. The documentation reflects the client-facing URLs, not the internal application paths.

Why this matters:

• Different groups uses different server URLs and path structures
• Selecting the wrong group may show incorrect endpoint URLs
• The authentication setup is shared between groups

Authentication Guide

The EnduranceTrio Tracker API requires Dual-Header Authentication. To test protected endpoints in Swagger UI, follow these steps:

1. Click the Authorize button at the top right of the page.
2. You will see a modal with two separate sections. You must configure both to successfully make requests:

Field Label	Corresponding Header	Value Format	Action
Account Name	ET-Owner	Your account identifier (e.g., system)	Enter ID & click Authorize
API Key	Authorization	Bearer <your_api_key>	Enter Key & click Authorize

Important: You must click the Authorize button for each field independently. Ensure both padlocks appear "locked" (closed) before closing the modal and testing endpoints.

Development

For detailed development documentation (API key management, database configuration, installation instructions, coding conventions, etc.), please refer to the Development Guide.

Quick Start

1. Prerequisites: Java 21, Maven, PostgreSQL
2. Clone: git clone [email protected]:EnduranceCode/endurancetrio-tracker.git
3. Configure: Set up application-secrets.yaml from template
4. Build: mvn clean install
5. Run: Use ./launch-app.sh or the provided IntelliJ run configuration

See the full Development Guide for comprehensive instructions.

Deployment

For deployment instructions (container architecture, server and reverse proxy setup, SSL certificate configuration, etc.), please refer to the Deployment Guide.

License

This project is licensed under the Functional Source License, Version 1.1, ALv2 Future License. See the LICENSE.md file for details.