API Overview
Welcome to the Heimdall API documentation. This API provides a comprehensive set of endpoints for managing GPS tracking data, system settings, and real-time communication.
Base URL
Production: https://api.elcto.com
Development: http://localhost:3000
All API endpoints are available under the /v1 prefix.
API Version
Current version: v1
All API endpoints are prefixed with /v1 (except health check and root endpoints).
Available APIs
Heimdall provides three main API interfaces:
🔹 REST API
Traditional RESTful API with full CRUD operations, pagination, and HATEOAS links.
- Endpoints:
/v1/* - Authentication: Bearer token
- Format: JSON
- Documentation: Interactive Swagger UI
🔹 GraphQL API
Flexible query language for efficient data fetching and mutations.
- Endpoint:
/v1/gql(requires authentication) - GraphiQL IDE:
/v1/graphiql(interactive interface, no auth) - Schema:
/v1/schema(SDL format, no auth) - Authentication: Required Bearer token for
/v1/gql - Features: Introspection, batching, type-safe queries
🔹 WebSocket API
Real-time bidirectional communication for live GPS updates and notifications.
- Endpoint:
ws://api.elcto.com/v1/ws - Protocol: WebSocket
- Features: Channel subscriptions, heartbeat monitoring, automatic reconnection
Key Features
- ✅ RESTful Design - Clean, predictable resource-based URLs
- ✅ HATEOAS Links - Self-documenting API with hypermedia links
- ✅ Authentication - Secure token-based authentication
- ✅ Rate Limiting - Protection against abuse
- ✅ Pagination - Efficient handling of large datasets
- ✅ Real-time Updates - WebSocket support for live data
- ✅ GraphQL - Flexible querying with exact data needs
- ✅ CORS Support - Environment-aware cross-origin requests
- ✅ Comprehensive Errors - Detailed error messages with codes
Quick Start
1. Get an API Token
Contact your administrator to obtain an API token.
2. Make Your First Request
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://api.elcto.com/v1/gps/current
3. Explore the API
Visit our Interactive Swagger UI to explore all available endpoints and try them out.
API Endpoints
| Category | Endpoints | Description |
|---|---|---|
| Health | GET /health, GET /v1/health | System health check |
| Info | GET /v1 | API version info |
| Auth | POST /v1/auth/* | Authentication & validation |
| GPS | /v1/gps/* | GPS data management |
| Settings | /v1/settings/* | System configuration |
| Stats | /v1/stats/* | Platform statistics |
| API Keys | /v1/api-keys/* | API key management (admin) |
| Roles | /v1/roles/* | Role management (admin) |
| Permissions | /v1/permissions/* | Permission management (admin) |
| Users | /v1/users/* | User management (admin) |
| WebSocket | WS /v1/ws | Real-time communication |
| GraphQL | POST /v1/gql, GET /v1/graphiql | GraphQL queries/mutations |
Response Format
All REST API responses follow a consistent format with HATEOAS links:
{
"data": {
"id": "abc-123",
"latitude": 51.5074,
"longitude": -0.1278
},
"_links": {
"self": "https://api.elcto.com/v1/gps/abc-123"
}
}