CHAPTER 5

Phase 2 - API Interface

Building on the Phase 1 data formats, Phase 2 defines RESTful APIs for system communication and data exchange. This chapter explores authentication, project management, material tracking, print job control, quality monitoring, and reporting endpoints that enable interoperability across the 3D construction printing ecosystem.

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:

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-446655440000

Content Negotiation

APIs support content negotiation via HTTP headers:

Accept: application/json
Content-Type: application/json

# Alternative formats (optional):
Accept: application/xml
Accept: application/yaml

Authentication 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:

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 Created

Print 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

Chapter Summary

Phase 2 of the WIA standard defines comprehensive RESTful APIs enabling system interoperability. Built on REST principles and using OAuth 2.0 authentication, these APIs provide secure, standardized access to construction 3D printing functions.

Project management APIs handle lifecycle from creation through completion. Material management endpoints track inventory, consumption, and certifications. Print job APIs control execution from submission through monitoring to completion. Quality assurance endpoints collect inspection data, track metrics, and generate compliance reports.

Consistent error handling, pagination, filtering, webhooks, and rate limiting ensure robust, production-ready API implementations. Versioning mechanisms allow evolution while maintaining backward compatibility. These APIs build directly on Phase 1 data formats, creating integrated ecosystem for data exchange and system coordination.

Key Takeaways

  1. REST Architecture: Resource-oriented URLs, standard HTTP methods, and stateless design create intuitive, scalable API interface familiar to developers worldwide.
  2. OAuth 2.0 Security: Industry-standard authentication with scoped permissions provides robust security while supporting diverse integration scenarios.
  3. Complete Lifecycle Coverage: APIs span entire project lifecycle—creation, material management, job execution, quality assurance—enabling comprehensive digital workflows.
  4. Production-Ready Features: Error handling, pagination, rate limiting, webhooks, and versioning ensure APIs meet enterprise requirements for reliability and performance.
  5. Data Format Integration: APIs exchange Phase 1 JSON data structures, creating seamless connection between data definition and system communication layers.

Review Questions

  1. Explain the core principles of REST architecture (resource-oriented, stateless, standard HTTP methods). Why is each principle important for API design, particularly in construction systems?
  2. Compare OAuth 2.0 to simpler authentication approaches like API keys or basic auth. What specific advantages does OAuth provide for 3D construction printing systems handling multiple organizations and permission levels?
  3. The job control API supports various states (queued, printing, paused, completed, failed, cancelled). For each state, explain what transitions are allowed and what actions make sense. Why are some transitions prohibited?
  4. Quality assurance requires collecting inspection data, tracking metrics over time, and generating compliance reports. Design a workflow showing how these three API sets work together for a complete quality management process.
  5. Analyze the trade-offs between polling (repeatedly calling GET /jobs/{id}/status) versus webhooks for monitoring job progress. When is each approach appropriate?
  6. The standard specifies API versioning via URL path (/wia/v1/, /wia/v2/). What challenges does API evolution create, and how does versioning address them? What happens when a client supports v1 but server only offers v2?

Looking Ahead

While Phase 2 APIs handle request-response interactions, real-time control of printing equipment requires different approaches. Chapter 6 explores Phase 3—Protocol specifications for real-time communication, robot control, material flow management, sensor data streaming, and safety systems using WebSocket and other continuous communication protocols.

← Chapter 4 Chapter 6: Phase 3 →