Skip to main content

Requirements

Implementation Requirements​

Core Capabilities​

Your implementation MUST support:

1. Object Management​

  • Object Types: Provide schemas for object types based on OPC UA Information Models
  • Object Discovery: Expose available manufacturing objects (equipment, processes, etc.)
  • Relationships: Support parent-child and compositional relationships at the instance object.

2. Data Access​

  • Current Values: Retrieve the latest values for object attributes
  • Data Quality: Include quality indicators with data points

3. Authentication & Authorization​

  • User Authentication: Secure API access with standard authentication mechanisms
  • Encryption: Encrypted (HTTPS) access only in production scenarios
  • Audit Logging: Optional: track API access and operations

4. Performance & Scalability​

  • Performance: Maintain performant responses to API calls, implementing strategies like paging or truncation only where necessary on the server-side
  • Concurrent Connections: Handle multiple simultaneous client connections

Core Capabilities​

Your implementation MAY support:

  • Relationships: Graph relationships, typically bi-directional, between instance objects
  • Historical Data: Optional: Query time-series data with time range filters
  • Aggregations: Support data aggregation (min, max, avg, count, etc.)
  • Caching: Utilize caching where appropriate

API Specification Compliance​

RESTful Endpoint Structure​

Your implementation should follow the i3X API specification:

Base URL: https://your-platform.example.com/i3x/v0/

Explore Endpoints:
  GET    /namespaces                  # List all namespaces
  GET    /objecttypes                 # List object type schemas
  POST   /objecttypes/query           # Query types by elementId(s)
  GET    /relationshiptypes           # List relationship types
  POST   /relationshiptypes/query     # Query relationship types by elementId(s)
  GET    /objects                     # List all objects
  POST   /objects/list                # Get objects by elementId(s)
  POST   /objects/related             # Get related objects

Query Endpoints:
  POST   /objects/value               # Get current values for object(s)
  POST   /objects/history             # Get historical values with time range

Update Endpoints:
  PUT    /objects/{elementId}/value   # Update object's current value
  PUT    /objects/{elementId}/history # Update historical values

Subscription Endpoints:
  GET    /subscriptions               # List all subscriptions
  POST   /subscriptions               # Create new subscription
  GET    /subscriptions/{id}          # Get subscription details
  DELETE /subscriptions/{id}          # Delete subscription
  POST   /subscriptions/{id}/register # Register objects to monitor
  POST   /subscriptions/{id}/unregister # Unregister objects
  GET    /subscriptions/{id}/stream   # SSE stream for real-time updates
  POST   /subscriptions/{id}/sync     # Poll queued updates

HTTP Methods and Semantics​

  • GET: Retrieve resources (read-only)
  • POST: Create resources or execute non-idempotent operations
  • PUT: Update entire resource (idempotent)

Standard HTTP Status Codes​

Your implementation should return appropriate status codes:

2xx Success:
  200 OK                  - Successful GET, PUT, PATCH
  201 Created             - Successful POST creating a resource
  204 No Content          - Successful DELETE

4xx Client Errors:
  400 Bad Request         - Invalid request syntax
  401 Unauthorized        - Missing or invalid authentication
  403 Forbidden           - Insufficient permissions
  404 Not Found           - Resource doesn't exist
  409 Conflict            - Conflicting state (e.g., duplicate object)
  422 Unprocessable       - Validation errors
  429 Too Many Requests   - Rate limit exceeded

5xx Server Errors:
  500 Internal Error      - Unexpected server error
  503 Service Unavailable - Temporary unavailability

Compliance Checklist​

Use this checklist to ensure your implementation meets minimum requirements:

Object Management​

  • List all objects (GET /objects)
  • Retrieve objects by elementId (POST /objects/list)
  • List object types (GET /objecttypes)
  • Query object types by elementId (POST /objecttypes/query)
  • Get related objects (POST /objects/related)
  • Support hierarchical relationships via parentId
  • List namespaces (GET /namespaces)
  • List relationship types (GET /relationshiptypes)

Data Access​

  • Get current values (POST /objects/value)
  • Include data quality and timestamp indicators
  • Support maxDepth for compositional hierarchies
  • Update current values (PUT /objects/{elementId}/value)

Historical Data Access (Optional)​

  • Query historical time-series data (POST /objects/history)
  • Update historical values (PUT /objects/{elementId}/history)

Authentication & Authorization​

  • Implement authentication
  • Require encrypted connections
  • Return appropriate 401/403 errors

Performance & Scalability​

  • Use strategies for maintain performance
  • Handle concurrent connections

HTTP Compliance​

  • Use correct HTTP methods
  • Return appropriate status codes
  • Include proper headers (Content-Type, etc.)
  • Support CORS
  • Implement proper error responses

Data Format​

  • Return JSON responses
  • Use RFC 3339 for timestamps
  • Include links in object responses
  • Support standard data types
  • Include quality indicators with data

Subscriptions (Optional)​

  • Create subscriptions (POST /subscriptions)
  • List subscriptions (GET /subscriptions)
  • Get subscription details (GET /subscriptions/{id})
  • Delete subscriptions (DELETE /subscriptions/{id})
  • Register objects to monitor (POST /subscriptions/{id}/register)
  • Unregister objects (POST /subscriptions/{id}/unregister)
  • SSE streaming (GET /subscriptions/{id}/stream)
  • Queue-based sync (POST /subscriptions/{id}/sync)

Versioning Strategy​

Your API should support versioning to allow evolution without breaking clients:

https://your-platform.example.com/i3x/v0/objects
https://your-platform.example.com/i3x/v0/objects

Best Practices​

  • Maintain backward compatibility within major versions
  • Deprecate features gracefully with advance notice
  • Document version differences clearly
  • Support at least N-1 versions (current and previous)