Skip to main content

​
Base URL and Versioning

The Water Quality Backend API is built with FastAPI and provides RESTful endpoints for managing water quality monitoring systems. 
Base URL: https://your-api-domain.com
The API currently does not use version prefixes (e.g., /v1/). All endpoints are accessed directly from the base URL.

​
Request and Response Format

All API requests and responses use JSON format with Content-Type: application/json.

​
Request Headers

Content-Type: application/json
Authorization: Bearer <your_jwt_token>

​
Response Structure

Successful responses typically follow this structure: 
{
  "message": "Operation successful",
  "data": {
    // Response data
  }
}

​
Common HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:
Status CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters or data
401Unauthorized - Missing or invalid authentication token
403Forbidden - Insufficient permissions
404Not Found - Resource not found
500Internal Server Error - Server encountered an error
502Bad Gateway - Error communicating with external services
504Gateway Timeout - Request timeout

​
Error Response Format

When an error occurs, the API returns a consistent error response: 
{
  "detail": "Error message describing what went wrong"
}
Error messages may be in Spanish in some cases. This is consistent with the current implementation in ~/workspace/source/app/features/auth/presentation/routes.py.

​
Example Error Responses

{
  "detail": "Credenciales inválidas"
}

​
CORS Configuration

The API is configured with permissive CORS settings to allow cross-origin requests from any domain. CORS Settings (from ~/workspace/source/app/__init__.py:19-26): 
allow_origins: ["*"]
allow_credentials: true
allow_methods: ["*"]
allow_headers: ["*"]
expose_headers: ["Content-Disposition"]
The Content-Disposition header is exposed to support file downloads (e.g., PDF reports).

​
Rate Limiting

Currently, the API does not implement rate limiting at the application level. However, you should implement rate limiting at the infrastructure level (reverse proxy, API gateway) for production deployments.

​
WebSocket Support for Real-Time Data

The API provides Socket.IO endpoints for real-time water quality monitoring data.

​
WebSocket Namespaces

The API implements two Socket.IO namespaces:

​
1. /receive/ - Meter Data Ingestion

Used by IoT meters to send real-time water quality measurements. Authentication: Requires a JWT token for meter connections Connection Example: 
const socket = io('https://your-api-domain.com/receive/', {
  transports: ['websocket'],
  extraHeaders: {
    'access_token': 'your_meter_jwt_token'
  }
});

socket.on('connect', () => {
  console.log('Meter connected');
});

// Send water quality data
socket.emit('message', {
  temperature: 25.5,
  ph: 7.2,
  turbidity: 1.5,
  // ... other parameters
});
Events:
  • connect - Connection established
  • message - Send meter readings
  • disconnect - Connection closed
  • error - Error occurred

​
2. /subscribe/ - Real-Time Data Subscription

Used by client applications to receive real-time updates from meters. Authentication: Requires a user JWT token Connection Example: 
const socket = io('https://your-api-domain.com/subscribe/', {
  transports: ['websocket'],
  query: {
    access_token: 'your_user_jwt_token',
    id_workspace: 'workspace_id',
    id_meter: 'meter_id'
  }
});

socket.on('message', (data) => {
  console.log('New water quality data:', data);
});
Events:
  • connect - Subscribed to meter updates
  • message - Receive meter readings
  • disconnect - Subscription ended
  • error - Error occurred
WebSocket connections require valid workspace access. Users must have VISITOR, MANAGER, or ADMINISTRATOR roles, or the workspace must be public.

​
WebSocket Authentication

WebSocket connections support two authentication methods:
  1. Header-based: HTTP_ACCESS_TOKEN header
  2. Query parameter: ?access_token=<token>
See ~/workspace/source/app/share/socketio/__init__.py:46-71 for implementation details.

​
API Endpoints Overview

The API is organized into the following feature modules:
ModuleBase PathDescription
Authentication/authUser registration, login, password reset, OAuth
Workspaces/workspacesWorkspace management and sharing
Meters/metersWater quality meter configuration
Alerts/alertsAlert configuration and notifications
Users/usersUser profile management
Monitoring/monitoringReal-time monitoring data
Analysis/analysisData analysis, reports, and predictions

​
Firebase Integration

The API uses Firebase for:
  • User authentication (Firebase Auth)
  • Real-time database operations
  • Password reset verification codes
Firebase initialization can be skipped in development by setting SKIP_FIREBASE_INIT=true.

​
Getting Started

1

Obtain an API Token

Register an account and authenticate to receive a JWT token. See the Authentication guide.
2

Make Your First Request

Use the token in the Authorization header:
curl -X GET https://your-api-domain.com/workspaces \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json"
3

Connect to WebSockets

Subscribe to real-time meter data using Socket.IO with your token.

​
Next Steps

  • Learn about API Authentication methods
  • Explore endpoint documentation for each module
  • Set up WebSocket connections for real-time data

Build docs developers (and LLMs) love

Get started for freeTalk to us