Phase 2 - API Interface

From Data to Systems Integration

Phase 1 data formats establish what information should be exchanged. Phase 2 API specifications define how systems exchange this information. Without standardized APIs, organizations must develop custom integrations for each partner, creating exponential complexity as networks grow. A collector working with ten recycling facilities would need ten different integration approaches. Manufacturers tracking products through multiple collection and processing organizations face similar complexity multiplication.

RESTful APIs solve this problem by providing uniform interfaces that all parties implement. Once a system supports the WIA E-Waste Management API, it can integrate with any other compliant system without custom development. This interoperability dramatically reduces integration costs while enabling the networked coordination necessary for effective e-waste management at scale.

REST Architecture Principles

The WIA API follows REST (Representational State Transfer) architectural principles, leveraging HTTP methods and status codes for clear, predictable interactions. RESTful design offers several advantages for e-waste management:

• Simplicity: Uses familiar HTTP protocol, lowering implementation barriers
• Statelessness: Each request contains all necessary information, improving reliability
• Cacheability: Responses can be cached, reducing load and improving performance
• Scalability: Stateless design and caching enable horizontal scaling
• Language Independence: Any language with HTTP support can implement the API

HTTP Methods Semantics

The API employs standard HTTP methods with consistent semantics:

Core API Endpoints

The standard defines endpoint categories covering device management, waste tracking, collection operations, processing documentation, material recovery, and compliance reporting. Each category groups related operations under a common path prefix.

Device Management API

Device registration and information retrieval form the foundation of tracking systems. These endpoints allow manufacturers to register products, authorized parties to retrieve information, and systems to update device status throughout the lifecycle.

POST /api/v1/devices
Register new device with manufacturer declaration
Request body: Device object per Phase 1 schema
Response: 201 Created with device_id and QR code URL

GET /api/v1/devices/{device_id}
Retrieve complete device information
Response: 200 OK with full device object including history

GET /api/v1/devices?manufacturer={mfr}&model={model}
Query devices by criteria
Response: 200 OK with array of matching devices

PATCH /api/v1/devices/{device_id}/status
Update device lifecycle status
Request body: {"status": "collected", "timestamp": "..."}
Response: 200 OK with updated device object

GET /api/v1/devices/{device_id}/materials
Retrieve material composition declaration
Response: 200 OK with bill of materials per Phase 1 schema

Collection and Tracking API

Collection events must be logged when devices enter the recycling stream. These endpoints support various collection methods including retail take-back, municipal drop-off, corporate ITAD, and specialized hazardous waste collection.

POST /api/v1/collections
Create new collection event
Request body: {
  "device_ids": ["uuid1", "uuid2", ...],
  "collection_method": "retail_takeback",
  "collector_id": "COL-12345",
  "location": {...},
  "timestamp": "2025-11-08T10:30:00Z",
  "condition_assessments": [...]
}
Response: 201 Created with collection_id

GET /api/v1/collections/{collection_id}
Retrieve collection event details
Response: 200 OK with collection object

GET /api/v1/collections?facility={fac_id}&date_range={range}
Query collections by criteria
Response: 200 OK with array of collections

POST /api/v1/collections/{collection_id}/devices
Add devices to existing collection batch
Request body: {"device_ids": ["uuid3", "uuid4"]}
Response: 200 OK with updated collection

Processing and Recovery API

Processing facilities document each stage of recycling operations. These endpoints record dismantling, shredding, separation, refining, and material recovery activities, creating complete processing audit trails.

POST /api/v1/processing/stages
Document processing stage completion
Request body: {
  "stage_type": "dismantling",
  "input_devices": ["uuid1", "uuid2", ...],
  "facility_id": "RC-US-CA-001",
  "timestamp": "2025-11-10T14:00:00Z",
  "outputs": [
    {
      "component_type": "battery",
      "quantity": 250,
      "total_weight_kg": 3.2,
      "disposition": "battery_recycler"
    }
  ]
}
Response: 201 Created with stage_id

POST /api/v1/recovery/materials
Report material recovery outcomes
Request body: {
  "source_devices": ["uuid1", "uuid2", ...],
  "facility_id": "RC-US-CA-001",
  "recovery_date": "2025-11-15",
  "recovered_materials": [
    {
      "material": "Copper",
      "cas_number": "7440-50-8",
      "weight_kg": 12.5,
      "purity_percentage": 95.2,
      "destination_facility": "SM-US-PA-001"
    }
  ]
}
Response: 201 Created with recovery_report_id

GET /api/v1/recovery/reports/{report_id}
Retrieve recovery report
Response: 200 OK with complete recovery documentation

Authentication and Authorization

E-waste data contains commercially sensitive information, personal data, and compliance documentation requiring access control. The API employs OAuth 2.0 for authentication with role-based access control (RBAC) for authorization.

OAuth 2.0 Implementation

The standard supports multiple OAuth 2.0 flows to accommodate different integration scenarios:

• Client Credentials: Server-to-server integration (recycler to manufacturer systems)
• Authorization Code: User-delegated access (consumer tracking their device)
• Refresh Token: Long-lived sessions without repeated authentication

POST /api/v1/oauth/token
Request access token
Request body: {
  "grant_type": "client_credentials",
  "client_id": "recycler_12345",
  "client_secret": "secret_xyz...",
  "scope": "devices:read collections:write"
}
Response: {
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "devices:read collections:write"
}

Usage:
GET /api/v1/devices/abc-123
Authorization: Bearer eyJhbG...

Role-Based Access Control

The standard defines stakeholder roles with associated permissions:

Rate Limiting and Performance

API implementations must handle varying load levels while preventing abuse. The standard specifies rate limiting policies and performance expectations to ensure reliable service.

Rate Limiting Policy

Requests are limited by role and operation type. Limits are communicated via HTTP headers:

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

HTTP 429 Too Many Requests
Response when limit exceeded:
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 1000 requests/hour exceeded",
  "retry_after": 1847
}

Performance Expectations

The standard specifies performance targets for API implementations:

• Response Time: 95th percentile < 500ms for simple queries
• Availability: 99.5% uptime (excluding planned maintenance)
• Throughput: Support 100 requests/second per facility
• Data Freshness: Updates visible within 5 seconds

Error Handling and Status Codes

Consistent error responses enable clients to handle failures gracefully. The API uses standard HTTP status codes with structured error bodies providing detailed information.

HTTP 400 Bad Request
{
  "error": "validation_error",
  "message": "Request body failed schema validation",
  "details": [
    {
      "field": "device.weight_kg",
      "error": "must be positive number",
      "value": -0.5
    },
    {
      "field": "device.weee_category",
      "error": "must be one of WEEE-1 through WEEE-6",
      "value": "WEEE-7"
    }
  ]
}

Versioning Strategy

APIs must evolve while maintaining backward compatibility for existing integrations. The standard employs URL-based versioning with clear deprecation policies.

Version Lifecycle

API versions follow a structured lifecycle:

• Current: Latest version, all new features, full support
• Supported: Previous version, security updates, 2-year support guarantee
• Deprecated: Older version, security-only updates, 6-month sunset notice
• Retired: No longer accessible, clients must upgrade

/api/v1/devices  - Current version (v1.3)
/api/v2/devices  - Future version (in development)

Version information in response headers:
X-API-Version: 1.3.2
X-API-Deprecated: false
X-API-Sunset-Date: null

Webhook Notifications

For real-time integration, the API supports webhooks that notify subscribers of events without polling. Organizations register webhook endpoints to receive notifications about device status changes, collection events, or processing completion.

POST /api/v1/webhooks
Register webhook endpoint
Request body: {
  "url": "https://recycler.example.com/wia-webhook",
  "events": ["device.collected", "processing.complete"],
  "secret": "webhook_secret_xyz"
}
Response: 201 Created with webhook_id

Webhook delivery (sent to registered URL):
POST https://recycler.example.com/wia-webhook
X-WIA-Event: device.collected
X-WIA-Signature: sha256=abc123...
{
  "event_type": "device.collected",
  "event_id": "evt_xyz",
  "timestamp": "2025-11-08T10:30:00Z",
  "data": {
    "device_id": "550e8400-e29b-41d4-a716-446655440000",
    "collection_id": "col_123",
    "collector_id": "COL-12345"
  }
}

Compliance Reporting API

Automated compliance reporting reduces administrative burden while improving data quality. These endpoints generate reports matching various regulatory requirements from standardized tracking data.

GET /api/v1/compliance/reports/epr
Generate Extended Producer Responsibility report
Parameters: 
  - jurisdiction (EU, California, Japan, etc.)
  - time_period (2025-Q1, 2025-annual)
  - format (JSON, PDF, XML)
Response: Jurisdiction-specific EPR report

GET /api/v1/compliance/reports/basel
Generate Basel Convention documentation
Parameters:
  - shipment_id
  - export_country
  - import_country
Response: Prior Informed Consent documentation

GET /api/v1/compliance/certificates/{device_id}
Retrieve recycling certificate for device
Response: PDF certificate with recovery documentation