WEDA Core API Fundamentals

Version: 0.1 (Early Access)

Overview: This document outlines the design principles, core concepts, and technical specifications of the WEDA Core API. It serves as the foundational reference for developers building integrations on top of the WEDA platform.

---

1. Core Concepts

Before calling the endpoints, it is essential to understand the WEDA Core data model and hierarchy.

1.1 Hierarchy & Organization

WEDA Core follows a strict hierarchical structure to ensure resource isolation and management.

• Organization: The root entity. All resources (Users, Devices, Stacks) belong to an Organization. Organizations can be nested (Parent-Child) to represent complex company structures or project groups.
• User: An identity that belongs to one or more organizations with specific roles (e.g., Admin, Viewer).
• Device: A physical edge node. It must be "claimed" into an organization to be managed.

1.2 Application Stacks

WEDA Core uses a container-centric approach for application management.

• Stack: A logical grouping of containers, defined by a Docker Compose file.
• Revision: Stacks are version-controlled. Every update creates a new immutable "Revision".
• Deployment: The mapping of a specific Stack Revision to a specific Device.

---

2. API Design Principles

The WEDA Core API is RESTful and follows standard HTTP semantics.

2.1 Authentication

• Mechanism: Bearer Token (JWT).
• Header: Authorization: Bearer <your_token>
• Lifecycle: Tokens have a limited lifespan. Your application must handle 401 Unauthorized responses by refreshing the token via the Auth endpoint.

2.2 Pagination

To ensure performance, list endpoints are paginated by default.

• Request Parameters:
  • skipCount (integer): Offset from the start.
  • maxResultCount (integer): Limit the number of records (Max: 1000).
• Response Structure:

  {
    "totalCount": 105,
    "items": [ ... ]
  }
• Best Practice: Always check totalCount to determine if you need to fetch subsequent pages.

2.3 Error Handling

We use standard HTTP status codes to indicate success or failure types.

Code	Meaning	Description
200	OK	Success.
201	Created	Resource successfully created (e.g., Device registered).
400	Bad Request	Validation failed (e.g., Invalid Docker Compose YAML).
403	Forbidden	You do not have permission to access this resource.
409	Conflict	The resource already exists (e.g., Duplicate Device Name).

---

3. Key Resources

This section details the primary resources available in v0.1.

3.1 Organization Resources

• Create Organization: POST /api/v1/orgs
• List Children: GET /api/v1/orgs/{id}/children
• Get Specific Org: GET /api/v1/orgs/{orgId}

3.2 Device Resources

• Register Device: POST /api/v1/devices
  • Register for physical provisioning.
• List Devices: GET /api/v1/devices
  • Supports filtering and pagination.
• Update Device: PUT /api/v1/devices/{id}
• Get Device Auth Info: GET /api/v1/devices/{deviceId}/auth
  • Crucial for device-side agent activation.

3.3 Container Resources

• Create Stack: POST /api/v1/container-stacks
  • Requires Base64 encoded docker-compose content.
• Get Stacks: GET /api/v1/container-stacks
• Batch Deploy: POST /api/v1/deployments
  • Supports atomic deployment to multiple device IDs.

---

4. Roadmap & Versioning

WEDA Core API is currently in v0.1 Early Access.

• Backward Compatibility: We strive to maintain backward compatibility, but breaking changes may occur in early versions.
• Future Capabilities (Target v0.2):
  • Remote Subnode Management: Native support for managing non-IP or lightweight downstream devices (e.g., Modbus sensors, iSensing) connected via WEDA node.
  • Virtual Device & Math Engine: Capabilities to create simulated devices driven by a built-in mathematical modeling engine for testing and digital twin scenarios.
  • TCP Tunnel: Secure, on-demand remote access tunnels to edge devices for troubleshooting and direct access without VPNs.

Looking for Tutorials? Please refer to the How-To-Use Guide for step-by-step installation and onboarding instructions.