REST API Architecture
The WIA standard adopts REST (Representational State Transfer) architectural style for its APIs. REST provides a proven, scalable, and widely-understood approach to distributed system communication.
REST Principles
WIA APIs follow core REST principles:
- Resource-Oriented: URLs represent resources (projects, materials, jobs) rather than actions
- Standard HTTP Methods: GET (retrieve), POST (create), PUT (update), DELETE (remove)
- Stateless: Each request contains all information needed; server maintains no session state
- Cacheable: Responses indicate whether they can be cached for performance
- Layered System: Clients can't tell if connected directly to server or through intermediaries
- Uniform Interface: Consistent patterns across all endpoints
API Base Structure
All WIA API endpoints follow consistent URL structure:
https://api.example.com/wia/v1/{resource}/{id}
Examples:
GET /wia/v1/projects
POST /wia/v1/projects
GET /wia/v1/projects/550e8400-e29b-41d4-a716-446655440000
PUT /wia/v1/projects/550e8400-e29b-41d4-a716-446655440000
DELETE /wia/v1/projects/550e8400-e29b-41d4-a716-446655440000Content Negotiation
APIs support content negotiation via HTTP headers:
Accept: application/json
Content-Type: application/json
# Alternative formats (optional):
Accept: application/xml
Accept: application/yamlAuthentication and Authorization
Security is paramount for construction systems handling sensitive project data and controlling expensive equipment. The WIA standard specifies authentication and authorization mechanisms.
OAuth 2.0 Authentication
The standard mandates OAuth 2.0 for authentication. OAuth provides:
- Industry-standard security with extensive tooling
- Token-based authentication avoiding password exposure
- Scoped permissions for fine-grained access control
- Token expiration and refresh mechanisms
- Support for different grant types (authorization code, client credentials)
Authentication Flow
1. Client requests authorization
POST /wia/v1/auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&scope=projects:read projects:write
2. Server responds with access token
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "projects:read projects:write"
}
3. Client uses token for API requests
GET /wia/v1/projects
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Permission Scopes
| Scope | Permissions | Use Case |
|---|---|---|
| projects:read | View project data | Design tools, reporting systems |
| projects:write | Create/modify projects | Design tools, project management |
| materials:read | View material inventory | Planning, procurement systems |
| materials:write | Update material inventory | Inventory management |
| jobs:control | Start/stop print jobs | Print control systems |
| quality:read | View quality data | Monitoring, reporting |
Project Management API
Project management endpoints handle the lifecycle of construction projects from creation through completion.
Create Project
POST /wia/v1/projects
Request:
{
"name": "Residential Building A1",
"type": "residential",
"location": {
"address": "123 Main Street",
"city": "Austin",
"state": "TX",
"country": "USA"
},
"geometry": { ... },
"materials": { ... },
"printParameters": { ... }
}
Response: 201 Created
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Residential Building A1",
"status": "created",
"createdAt": "2025-03-01T10:00:00Z",
"links": {
"self": "/wia/v1/projects/550e8400-e29b-41d4-a716-446655440000",
"jobs": "/wia/v1/projects/550e8400-e29b-41d4-a716-446655440000/jobs"
}
}List Projects
GET /wia/v1/projects?status=active&limit=20&offset=0
Response: 200 OK
{
"projects": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Residential Building A1",
"status": "printing",
"progress": 0.35
},
{ ... }
],
"total": 45,
"limit": 20,
"offset": 0,
"links": {
"next": "/wia/v1/projects?status=active&limit=20&offset=20"
}
}Update Project
PUT /wia/v1/projects/550e8400-e29b-41d4-a716-446655440000
Request:
{
"status": "approved",
"approvals": {
"structural": {
"approved": true,
"approvedBy": "John Smith, PE",
"date": "2025-03-05T14:30:00Z"
}
}
}
Response: 200 OK
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "approved",
"updatedAt": "2025-03-05T14:30:00Z"
}Material Management API
Material tracking ensures adequate inventory and maintains material traceability for quality and compliance.
Material Inventory
GET /wia/v1/materials/inventory
Response: 200 OK
{
"materials": [
{
"id": "WIA-CONCRETE-STD-001",
"name": "Standard Printable Concrete",
"quantity": 15000,
"unit": "kg",
"location": "Silo A",
"batchNumber": "20250301-A",
"expiryDate": "2025-03-15",
"certifications": [
{
"type": "material-test",
"date": "2025-02-28",
"results": {
"compressiveStrength": 32.5,
"flowRate": 1200
}
}
]
}
]
}Material Consumption Tracking
POST /wia/v1/materials/consumption
Request:
{
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"materialId": "WIA-CONCRETE-STD-001",
"quantity": 500,
"unit": "kg",
"timestamp": "2025-03-10T08:30:00Z",
"jobId": "job-12345"
}
Response: 201 Created
{
"id": "consumption-98765",
"remainingInventory": 14500,
"lowStockWarning": false
}Material Certification
POST /wia/v1/materials/certifications
Request:
{
"materialId": "WIA-CONCRETE-STD-001",
"batchNumber": "20250301-A",
"testType": "compressive-strength",
"testDate": "2025-03-01",
"testLab": "Acme Testing Labs",
"results": {
"7day": 22.5,
"28day": 32.5,
"unit": "MPa"
},
"certificate": {
"number": "CERT-2025-001234",
"documentUrl": "https://storage.example.com/certs/2025-001234.pdf"
}
}
Response: 201 CreatedPrint Job API
Print job endpoints control the execution of 3D printing operations from submission through completion.
Submit Print Job
POST /wia/v1/jobs
Request:
{
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"name": "Building A1 - Foundation Layer 1-50",
"priority": "normal",
"schedule": {
"startTime": "2025-03-12T06:00:00Z",
"estimatedDuration": 14400
},
"layers": {
"start": 1,
"end": 50
},
"printerId": "printer-alpha-01"
}
Response: 201 Created
{
"id": "job-12345",
"status": "queued",
"queuePosition": 2,
"estimatedStartTime": "2025-03-12T06:00:00Z",
"links": {
"self": "/wia/v1/jobs/job-12345",
"status": "/wia/v1/jobs/job-12345/status",
"cancel": "/wia/v1/jobs/job-12345/cancel"
}
}Job Status Monitoring
GET /wia/v1/jobs/job-12345/status
Response: 200 OK
{
"id": "job-12345",
"status": "printing",
"progress": {
"currentLayer": 23,
"totalLayers": 50,
"percentage": 0.46,
"elapsedTime": 6624,
"estimatedRemaining": 7776
},
"printer": {
"id": "printer-alpha-01",
"status": "operational",
"temperature": 24.5,
"materialLevel": 0.78
},
"quality": {
"lastInspection": "2025-03-12T08:45:00Z",
"dimensionalAccuracy": "within-tolerance",
"layerAdhesion": "good"
}
}Job Control
POST /wia/v1/jobs/job-12345/pause
Response: 200 OK
{
"id": "job-12345",
"status": "paused",
"pausedAt": "2025-03-12T09:15:00Z",
"reason": "manual-pause"
}
POST /wia/v1/jobs/job-12345/resume
Response: 200 OK
{
"id": "job-12345",
"status": "printing",
"resumedAt": "2025-03-12T09:20:00Z"
}| Job Status | Description | Available Actions |
|---|---|---|
| queued | Waiting to start | cancel, modify schedule |
| printing | Currently executing | pause, cancel, monitor |
| paused | Temporarily stopped | resume, cancel |
| completed | Successfully finished | view reports, archive |
| failed | Error occurred | view logs, retry, modify |
| cancelled | Manually stopped | view partial results |
Quality Assurance API
Quality endpoints collect inspection data, track metrics, and generate compliance reports.
Record Inspection
POST /wia/v1/quality/inspections
Request:
{
"jobId": "job-12345",
"layer": 25,
"timestamp": "2025-03-12T08:45:00Z",
"inspector": "Jane Doe",
"method": "laser-scan",
"measurements": {
"dimensionalAccuracy": {
"horizontal": {
"deviation": 2.3,
"tolerance": 5.0,
"status": "pass"
},
"vertical": {
"deviation": 4.1,
"tolerance": 10.0,
"status": "pass"
}
},
"surfaceQuality": {
"roughness": 3.2,
"waviness": 6.5,
"status": "pass"
}
},
"overallStatus": "pass"
}
Response: 201 Created
{
"id": "inspection-789",
"status": "recorded",
"complianceScore": 95.7
}Quality Metrics
GET /wia/v1/quality/metrics?jobId=job-12345
Response: 200 OK
{
"jobId": "job-12345",
"period": {
"start": "2025-03-12T06:00:00Z",
"end": "2025-03-12T10:00:00Z"
},
"metrics": {
"dimensionalAccuracy": {
"mean": 2.8,
"stdDev": 0.9,
"withinTolerance": 0.98
},
"layerAdhesion": {
"rating": "excellent",
"failureRate": 0.002
},
"materialConsistency": {
"flowRateVariation": 0.05,
"temperatureVariation": 1.2
}
},
"overallScore": 94.3
}Compliance Reporting
GET /wia/v1/quality/compliance-report?projectId=550e8400-e29b-41d4-a716-446655440000
Response: 200 OK
{
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"reportDate": "2025-03-15",
"buildingCode": "IBC-2021",
"compliance": {
"structural": {
"status": "compliant",
"tests": [
{
"type": "compressive-strength",
"required": "≥25 MPa",
"achieved": "32.5 MPa",
"status": "pass"
}
]
},
"dimensional": {
"status": "compliant",
"tolerances": "98.7% within specification"
},
"materials": {
"status": "compliant",
"certifications": "all-valid"
}
},
"overallStatus": "compliant",
"certificateNumber": "WIA-CERT-2025-001234",
"documentUrl": "https://storage.example.com/compliance/2025-001234.pdf"
}Error Handling
Consistent error handling helps developers understand and resolve issues. All WIA APIs use standard HTTP status codes and structured error responses.
HTTP Status Codes
| Code | Meaning | Usage |
|---|---|---|
| 200 | OK | Successful request |
| 201 | Created | Resource successfully created |
| 400 | Bad Request | Invalid request data |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource state conflict |
| 500 | Internal Error | Server error |
Error Response Format
{
"error": {
"code": "INVALID_MATERIAL_SPECIFICATION",
"message": "Material compressive strength must be between 10 and 100 MPa",
"details": {
"field": "materials.primary.properties.compressiveStrength",
"providedValue": 150,
"allowedRange": [10, 100]
},
"timestamp": "2025-03-12T10:15:00Z",
"requestId": "req-abc123"
}
}Pagination and Filtering
List endpoints support pagination and filtering to handle large datasets efficiently.
GET /wia/v1/projects?status=active&type=residential&limit=20&offset=40&sortBy=createdAt&order=desc
Response:
{
"projects": [ ... ],
"pagination": {
"total": 125,
"limit": 20,
"offset": 40,
"hasMore": true
},
"links": {
"first": "/wia/v1/projects?status=active&type=residential&limit=20&offset=0",
"prev": "/wia/v1/projects?status=active&type=residential&limit=20&offset=20",
"self": "/wia/v1/projects?status=active&type=residential&limit=20&offset=40",
"next": "/wia/v1/projects?status=active&type=residential&limit=20&offset=60",
"last": "/wia/v1/projects?status=active&type=residential&limit=20&offset=120"
}
}Webhooks and Event Notifications
For real-time updates, the API supports webhook notifications. Systems register webhook endpoints to receive event notifications.
POST /wia/v1/webhooks
Request:
{
"url": "https://your-system.example.com/webhooks/wia",
"events": [
"job.started",
"job.completed",
"job.failed",
"quality.inspection-failed"
],
"secret": "your-webhook-secret"
}
# When event occurs, POST sent to webhook URL:
POST https://your-system.example.com/webhooks/wia
Content-Type: application/json
X-WIA-Signature: sha256=...
{
"event": "job.completed",
"timestamp": "2025-03-12T14:30:00Z",
"data": {
"jobId": "job-12345",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"duration": 14235,
"layersCompleted": 50
}
}Rate Limiting
To ensure fair usage and system stability, APIs implement rate limiting with clear feedback.
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 523
X-RateLimit-Reset: 1647097200
# When limit exceeded:
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1647097200
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "API rate limit exceeded",
"retryAfter": 300
}
}API Versioning
API versions are specified in the URL path, allowing backward compatibility as APIs evolve.
/wia/v1/projects # Version 1
/wia/v2/projects # Version 2 (when released)
# Version negotiation via header (optional):
Accept: application/vnd.wia.v1+json