Telemetry Harbor V2 API Launch
We've rebuilt our ingest API from the ground up in Go, making V2 faster and more efficient than ever before.
What's New in V2
Complete Rewrite for Performance
Our V2 API represents a ground-up rebuild focused on performance and scalability. This architectural improvement delivers faster response times and better resource utilization.
Stricter Data Standards
V2 introduces more rigorous validation to ensure data consistency across all harbor ingestions.
Time Format Requirements Time values must now use ISO 8601 format exclusively. We no longer accept flexible datetime formats that could introduce timezone ambiguity or parsing errors.
Numeric Value Enforcement All values must be numeric. We've removed support for boolean workarounds and other data type flexibility that could cause downstream processing issues.
Simplified Response Handling
The new API provides cleaner, more consistent responses. Single point ingestion returns immediate confirmation with ship and cargo identifiers. Batch operations return the processed count without unnecessary job tracking complexity.
Technical Changes
Data Model Updates
The core sensor data structure has been refined:
{
"time": "2025-08-10T14:30:00Z",
"ship_id": "device_001",
"cargo_id": "sensor_temp",
"value": 23.5
}
Architecture Improvements
V2 represents a complete platform rebuild focused on performance and reliability. The new architecture eliminates previous bottlenecks and provides more consistent response times under load.
Performance Improvements
Internal benchmarking shows significant improvements across all metrics:
- Single point ingestion: 60% faster response times
- Batch processing: 3x throughput improvement
- Memory usage: 40% reduction
- Concurrent request handling: Substantially improved
Migration Considerations
Required Format Changes
Time Values:
// V1 (flexible)
"time": "2025-08-10 14:30:00"
// V2 (ISO 8601 required)
"time": "2025-08-10T14:30:00Z"
Value Validation: All sensor values must be valid numbers. Any boolean-to-number conversions or string representations need to be handled client-side.
Error Responses: V2 provides more detailed validation errors, including field-specific feedback for batch operations.
Backward Compatibility
V1 remains fully operational during this transition. Existing integrations continue to work without modification, allowing teams to migrate at their own pace.
We recommend testing V2 endpoints in development environments before switching production traffic. The performance gains are substantial, but the stricter validation may require adjustments to existing data preparation logic.
Implementation Details
Platform Optimizations
The new implementation streamlines data processing and improves queue management efficiency. We've enhanced the validation system to catch data issues earlier, while maintaining the same caching and rate limiting capabilities you rely on.
Getting Started with V2
The endpoint structure remains identical:
POST /ingest/{harbor_id}for single data pointsPOST /ingest/{harbor_id}/batchfor batch operations
Authentication and rate limiting work exactly as in V1, using the same API key headers and harbor-specific limits.
Next Steps
Review your current data formatting, particularly timestamp generation and value type handling. The stricter V2 validation will catch issues that V1 might have processed silently.
Consider the performance benefits for high-throughput use cases. The improved concurrent handling makes V2 particularly valuable for applications with burst traffic patterns.
Plan your migration timeline based on your team's capacity. V1 support continues for now, so there's no rush to migrate everything at once.