🔌 Phase 2 - API Interface (Sensor Network APIs)

Introduction to API Standards

Application Programming Interfaces (APIs) are the connective tissue of modern monitoring systems. Phase 2 of the WIA standard defines comprehensive API specifications that enable programmatic access to ecosystem data, supporting automated workflows, real-time dashboards, analysis pipelines, and system integrations. While Phase 1 standardizes data formats, Phase 2 standardizes how that data is accessed, queried, and transmitted.

The WIA API standard embraces RESTful design principles for simplicity and broad compatibility while adding real-time streaming capabilities for sensor networks. This hybrid approach serves both batch data access patterns common in research and continuous data streams essential for operational monitoring.

RESTful API Architecture

The WIA REST API follows industry-standard HTTP methods and status codes, making it immediately familiar to developers while providing monitoring-specific functionality:

Core Endpoints

Query Parameters

All endpoints support rich filtering through standardized query parameters enabling precise data retrieval:

• Temporal filtering: start_date, end_date, timestamp
• Spatial filtering: bbox (bounding box), point, radius, polygon
• Taxonomic filtering: taxon, kingdom, class, family
• Quality filtering: quality_min, validated_only
• Pagination: limit, offset, page
• Sorting: sort_by, order (asc/desc)
• Format: format (json, csv, geojson)

Example API Request

GET /api/v1/observations?
    taxon=Haliaeetus+leucocephalus&
    start_date=2025-01-01&
    end_date=2025-12-31&
    bbox=-123.0,47.0,-122.0,48.0&
    quality_min=0.8&
    limit=100&
    format=json

Authorization: Bearer YOUR_API_KEY
Accept: application/json

Response Format

All API responses follow a consistent structure with metadata, data, and pagination information:

{
  "status": "success",
  "api_version": "1.0",
  "request_id": "req-12345",
  "timestamp": "2025-12-26T15:30:00Z",
  "query": {
    "taxon": "Haliaeetus leucocephalus",
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "bbox": [-123.0, 47.0, -122.0, 48.0]
  },
  "pagination": {
    "total_records": 342,
    "returned_records": 100,
    "page": 1,
    "total_pages": 4,
    "next_page": "/api/v1/observations?page=2&..."
  },
  "data": [
    {
      "observation_id": "OBS-2025-001",
      "timestamp": "2025-03-15T10:30:00Z",
      "taxon": {...},
      "location": {...},
      ...
    },
    ...
  ]
}

Authentication and Authorization

Security is paramount for ecosystem monitoring data, protecting sensitive species locations while enabling appropriate access. WIA supports multiple authentication mechanisms:

API Keys

Simple authentication via API keys passed in request headers: Authorization: Bearer YOUR_API_KEY. Suitable for server-to-server communication and script-based access.

OAuth 2.0

Industry-standard authorization framework supporting user authentication, scoped permissions, and token refresh. Ideal for web applications and services requiring granular access control.

JWT Tokens

JSON Web Tokens enable stateless authentication with embedded claims about user identity and permissions. Useful for distributed systems and microservices architectures.

Access Control

Fine-grained permissions control what data users can access and modify:

• Public: Openly accessible data with no authentication required
• Registered: Requires authentication but available to all registered users
• Group: Restricted to specific user groups or organizations
• Private: Available only to data owners and explicitly authorized users
• Embargoed: Temporarily restricted with scheduled public release

Real-Time Streaming APIs

Sensor networks generate continuous data streams requiring different access patterns than batch queries. WIA provides real-time streaming APIs using WebSocket and MQTT protocols:

WebSocket Connections

WebSocket provides bidirectional communication channels enabling real-time data push from servers to clients. Applications establish persistent connections and receive sensor updates as they occur:

// Client-side JavaScript example
const ws = new WebSocket('wss://api.ecosystem-monitoring.org/stream');

ws.onopen = () => {
  // Subscribe to specific sensors
  ws.send(JSON.stringify({
    action: 'subscribe',
    sensors: ['TEMP-001', 'TEMP-002'],
    filters: {
      quality_min: 0.8
    }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('New sensor reading:', data);
  updateDashboard(data);
};

MQTT for IoT Devices

Message Queuing Telemetry Transport (MQTT) is a lightweight publish-subscribe protocol ideal for constrained IoT devices with limited bandwidth and power. Sensors publish data to topics; subscribers receive updates:

# Topic structure
sensors/{sensor_id}/data
sensors/{sensor_id}/status
sensors/{sensor_id}/alerts

# Example MQTT publish
Topic: sensors/TEMP-001/data
Payload: {
  "timestamp": "2025-12-26T15:30:00Z",
  "value": 12.3,
  "unit": "celsius",
  "quality": "good"
}

Bulk Data Access

Large-scale analyses require efficient bulk data access beyond individual API queries. WIA supports multiple bulk access patterns:

Asynchronous Queries

For queries returning large result sets, clients submit requests that are processed asynchronously. The API returns a job ID; clients poll for completion and download results when ready:

POST /api/v1/bulk-query
{
  "query": {
    "dataset": "all-observations",
    "start_date": "2020-01-01",
    "end_date": "2025-12-31",
    "format": "csv"
  }
}

Response:
{
  "job_id": "bulk-123",
  "status": "queued",
  "estimated_time": "300 seconds",
  "status_url": "/api/v1/jobs/bulk-123"
}

# Check status
GET /api/v1/jobs/bulk-123

# Download when ready
GET /api/v1/jobs/bulk-123/download

Data Dumps

Pre-generated complete datasets available for download without querying:

Data Submission APIs

Beyond data retrieval, WIA APIs support data submission enabling contributors to upload observations and sensor data:

Single Observation Submission

POST /api/v1/observations
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "wia_version": "1.0",
  "schema_type": "species-observation",
  "timestamp": "2025-12-26T14:00:00Z",
  "taxon": {...},
  "location": {...},
  ...
}

Response:
{
  "status": "success",
  "observation_id": "OBS-2025-12345",
  "validation": {
    "passed": true,
    "quality_score": 0.95
  }
}

Batch Submission

Multiple observations submitted simultaneously for efficiency:

POST /api/v1/observations/batch
Content-Type: application/json

{
  "observations": [
    {...observation 1...},
    {...observation 2...},
    {...observation 3...}
  ]
}

Response:
{
  "status": "success",
  "submitted": 3,
  "accepted": 3,
  "rejected": 0,
  "results": [
    {"id": "OBS-001", "status": "accepted"},
    {"id": "OBS-002", "status": "accepted"},
    {"id": "OBS-003", "status": "accepted"}
  ]
}

Error Handling

Robust error handling with clear messages helps developers diagnose and resolve issues:

Rate Limiting

Fair use policies prevent abuse while ensuring service availability:

• Anonymous users: 100 requests/hour
• Authenticated users: 1,000 requests/hour
• Premium/Research accounts: 10,000 requests/hour
• Bulk downloads: Special limits based on data volume

Rate limit headers inform clients of their status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1735228800

API Versioning

APIs evolve over time. WIA uses URL-based versioning ensuring backward compatibility while enabling innovation:

https://api.ecosystem-monitoring.org/v1/observations
https://api.ecosystem-monitoring.org/v2/observations

Deprecation policies provide ample warning before removing old versions, with minimum 12-month support periods for major versions.

Documentation and Developer Tools

Comprehensive documentation and tooling accelerate integration:

OpenAPI Specification

Machine-readable API specifications enable automatic tool generation. The WIA OpenAPI spec provides complete endpoint documentation, request/response examples, and validation schemas.

SDKs and Client Libraries

Official software development kits for popular languages simplify API integration:

• JavaScript/TypeScript: npm package for web and Node.js applications
• Python: pip package for data science and analysis
• R: CRAN package for statistical computing
• Java: Maven package for enterprise applications

Interactive Documentation

Web-based API explorer allows testing endpoints directly in the browser without writing code. Developers can experiment with queries, view responses, and generate code examples.