API Reference

HydroLink Plus API Reference

Table of Contents

1. Introduction
2. Authentication and Security
3. Endpoints
   • Meter Registration
   • Data Transmission
   • Control Actions
   • OTA Updates
   • Notifications and Alerts
   • Usage Insights
   • Billing and Payment
   • Water Quality Monitoring
4. Response Codes
5. Error Handling
6. Usage Examples
7. Conclusion

---

Introduction

The HydroLink Plus API serves as the backbone for communication between smart water meters, central Authority Servers, and user portals (both mobile apps and dashboards). It supports secure data exchange, device management, and real-time analytics for efficient water management.

---

Authentication and Security

To ensure secure interactions, the API includes:

1. OAuth 2.0: Provides token-based authentication for devices, users, and administrators.
2. TLS Encryption: Secures all API requests and responses.
3. HMAC Authentication: For data integrity and non-repudiation.
4. IP Whitelisting: Allows API calls only from trusted IPs (used for Authority Servers).
5. Rate Limiting: Limits excessive API calls from a single source to prevent abuse.

---

Endpoints

Meter Registration

Description: Registers a new water meter in the system, associating it with a unique ID and location.

• Method: POST
• Endpoint: /api/meter/register
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <admin_token>
• Request Body:

  {
      "meter_id": "unique-meter-id",
      "location": {
          "latitude": 10.2345,
          "longitude": 20.5432,
          "address": "123 Main Street, City"
      },
      "firmware_version": "1.0.0",
      "mac_address": "xx:xx:xx:xx:xx:xx"
  }

• Response:

  {
      "status": "success",
      "message": "Meter registered successfully",
      "meter_token": "generated-meter-token"
  }

---

Data Transmission

Description: Transmits sensor readings (e.g., water usage, quality) to the central server.

• Method: POST
• Endpoint: /api/data/transmit
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <meter_token>
• Request Body:

  {
      "meter_id": "unique-meter-id",
      "timestamp": "2024-11-18T12:00:00Z",
      "data": {
          "water_usage": {
              "flow_rate": 1.25,
              "total_usage": 50.3
          },
          "water_quality": {
              "ph": 7.5,
              "turbidity": 1.2,
              "conductivity": 500
          }
      }
  }

• Response:

  {
      "status": "success",
      "message": "Data transmitted successfully",
      "acknowledgment_id": "abc123"
  }

---

Control Actions

Description: Allows remote control of water meter hardware (e.g., motorized valves).

• Method: POST
• Endpoint: /api/meter/control
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <meter_token>
• Request Body:

  {
      "meter_id": "unique-meter-id",
      "action": "open_valve",
      "reason": "scheduled maintenance complete"
  }

• Response:

  {
      "status": "success",
      "message": "Action executed successfully",
      "timestamp": "2024-11-18T12:05:00Z"
  }

---

OTA Updates

Description: Checks and downloads firmware updates for the water meter.

• Method: GET
• Endpoint: /api/ota/check
• Headers:
  • Authorization: Bearer <meter_token>
• Response:

  {
      "status": "update_available",
      "version": "1.0.2",
      "release_notes": "Bug fixes and performance improvements",
      "update_url": "https://updates.hydrolinkplus.com/firmware/1.0.2.bin"
  }

---

Notifications and Alerts

Description: Sends alerts from meters (e.g., tampering, leaks).

• Method: POST
• Endpoint: /api/meter/alert
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <meter_token>
• Request Body:

  {
      "meter_id": "unique-meter-id",
      "alert_type": "tampering_detected",
      "details": "Tampering detected at 2024-11-18T10:00:00Z"
  }

• Response:

  {
      "status": "success",
      "message": "Alert received and logged"
  }

---

Usage Insights

Description: Retrieves usage statistics and trends.

• Method: GET
• Endpoint: /api/meter/usage
• Headers:
  • Authorization: Bearer <user_token>
• Response:

  {
      "status": "success",
      "data": {
          "daily_usage": 50.3,
          "weekly_usage": 310.2,
          "forecasted_monthly_usage": 1200.5
      }
  }

---

Billing and Payment

Description: Retrieves billing information for a user.

• Method: GET
• Endpoint: /api/user/billing
• Headers:
  • Authorization: Bearer <user_token>
• Response:

  {
      "status": "success",
      "data": {
          "current_bill": 45.5,
          "due_date": "2024-12-01",
          "past_due": 0
      }
  }

---

Water Quality Monitoring

Description: Retrieves water quality details for a specific meter.

• Method: GET
• Endpoint: /api/meter/quality
• Headers:
  • Authorization: Bearer <user_token>
• Response:

  {
      "status": "success",
      "data": {
          "ph": 7.5,
          "turbidity": 1.2,
          "conductivity": 500,
          "last_updated": "2024-11-18T12:00:00Z"
      }
  }

---

Response Codes

Code	Description
200	Success
201	Resource Created
400	Bad Request
401	Unauthorized Access
403	Forbidden
404	Resource Not Found
429	Too Many Requests
500	Internal Server Error

---

Error Handling

Sample Error Response:

{
    "status": "error",
    "code": 401,
    "message": "Unauthorized access. Token expired."
}

---

Conclusion

This expanded API reference provides comprehensive documentation for interacting with HydroLink Plus, covering all major functionalities such as data transmission, remote control, and analytics. Its secure, scalable architecture ensures reliable communication between devices and the central server.