# API Usage and Integration Patterns for KCloud-Platform-IoT: A Complete Developer Guide

> Explore KCloud-Platform-IoT API usage and integration patterns in this developer guide. Learn about REST endpoints, DTO-driven commands, and declarative annotations for security and logging.

- Repository: [laokou/kcloud-platform-iot](https://github.com/koushenhai/kcloud-platform-iot)
- Tags: how-to-guide
- Published: 2026-03-05

---

**KCloud-Platform-IoT exposes versioned REST endpoints through layered Spring Boot adapters that use DTO-driven commands and queries, with cross-cutting concerns handled via declarative annotations for idempotency, audit logging, and security.**

KCloud-Platform-IoT is an open-source IoT management platform built on Spring Boot 4 and Spring Cloud 2025, following Alibaba COLA architecture conventions. Understanding the API usage and integration patterns for KCloud-Platform-IoT enables developers to interact with device management, product catalogs, and thing models through a consistent, secure interface. This guide examines the actual source implementation to demonstrate how controllers, service contracts, and data transfer objects collaborate to handle HTTP requests in this microservices ecosystem.

## Layered Architecture Overview

KCloud-Platform-IoT implements a **layered micro-service architecture** that cleanly separates HTTP concerns from business logic. The architecture consists of four primary layers:

- **Adapters (REST Controllers)** – Expose HTTP/JSON endpoints under the `/v1/` prefix. Controllers reside in the `laokou-iot-adapter` module.
- **Service Interfaces (`*ServiceI`)** – Define business contracts in the `laokou-iot-client` modules, implemented by `*ServiceImpl` classes in the `laokou-iot-app` modules.
- **DTOs (Cmd/Qry/CO)** – Lightweight request/response objects. Commands (`*Cmd`) handle writes, Queries (`*Qry`) handle reads, and Client Objects (`*CO`) represent responses.
- **Cross-cutting concerns** – Handled declaratively via `@Idempotent`, `@OperateLog`, `@TraceLog`, and Spring Security annotations applied directly on controller methods.

All public APIs are documented with **OpenAPI** annotations (`@Operation`, `@Tag`) and auto-generate Swagger UI via Springdoc.

## Request Flow Through the System

The typical HTTP request follows a strict pipeline through the architecture:

```

HTTP Request → Adapter (Controller) → ServiceI (Business contract) → ServiceImpl (业务实现) → Repository/Message Queue/External System

```

The **controller** validates incoming payloads using `@Validated` and forwards either a `Cmd` or `Qry` object to the service interface. The **service implementation** executes core business logic—such as persisting device metadata or publishing MQTT events. Finally, responses are wrapped in `Result<T>` (or `Page<T>` for pagination) and serialized to a standard JSON envelope by the global exception handler.

## Core API Groups and Endpoints

The platform organizes IoT functionality into domain-specific controllers, each following consistent naming conventions and base paths.

### Device Management

The [`DevicesController`](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/DevicesController.java) handles device lifecycle operations at the base path `/v1/devices`. 

- **Service Interface**: `DevicesServiceI` (defined in `laokou-iot-client`)
- **Key DTOs**: `DeviceSaveCmd`, `DeviceModifyCmd`, `DevicePageQry`, `DeviceExportCmd`, `DeviceCO`

### Product Management

The [`ProductsController`](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/ProductsController.java) manages product definitions at `/v1/products`.

- **Service Interface**: `ProductsServiceI`
- **Key DTOs**: `ProductSaveCmd`, `ProductModifyCmd`, `ProductPageQry`, `ProductExportCmd`, `ProductCO`

### Thing Model and Product Category

- **Thing Models**: [`ThingModelsController`](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/ThingModelsController.java) exposes `/v1/thing-models` with `ThingModelSaveCmd`, `ThingModelPageQry`, and `ThingModelCO`.
- **Product Categories**: [`ProductCategorysController`](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/ProductCategorysController.java) exposes `/v1/product-categorys` with corresponding `ProductCategory` DTOs.

## Practical API Integration Examples

### Creating a Device

To create a device, POST a JSON payload that maps to `DeviceSaveCmd`:

```bash
curl -X POST https://api.my-iot.com/v1/devices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{
        "name": "TempSensor-001",
        "productId": 12,
        "devEui": "A1B2C3D4E5F6",
        "description": "Warehouse temperature sensor"
      }'

```

This request flows through `DevicesServiceI.saveDevice` to [`DevicesServiceImpl.saveDevice`](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-app/src/main/java/org/laokou/iot/device/service/DevicesServiceImpl.java).

### Paginated Queries

For paginated device listings, use the `DevicePageQry` DTO:

```bash
curl -X POST https://api.my-iot.com/v1/devices/page \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{
        "pageNum": 1,
        "pageSize": 20,
        "name": "TempSensor"
      }'

```

The endpoint returns `Result<Page<DeviceCO>>`, where the `Result` wrapper provides standard status codes and the `Page` object contains the collection of `DeviceCO` objects.

### Bulk Import and Export

**Import** operations accept `multipart/form-data` and map to `DeviceImportCmd`:

```bash
curl -X POST https://api.my-iot.com/v1/devices/import \
  -H "Authorization: Bearer <jwt-token>" \
  -F "files=@/path/to/devices.xlsx"

```

**Export** operations stream Excel files using EasyExcel or Apache POI:

```bash
curl -X POST https://api.my-iot.com/v1/devices/export \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{"ids": [101, 102, 103]}' \
  -o devices.xlsx

```

The export triggers `DevicesServiceI.exportDevice`, which handles the streaming response.

## Security and Cross-Cutting Concerns

### Method-Level Security

All endpoints are protected with **Spring Security** expressions. For example, device creation requires specific authorities:

```java
@PreAuthorize("hasAuthority('write') and hasAuthority('iot:device:save')")

```

Users must obtain JWT tokens from the **auth** service that contain these authority strings.

### Idempotent Writes

The `@Idempotent` annotation prevents duplicate submissions on POST and PUT operations. This is implemented via token-based verification or Redis distributed locks, ensuring that network retries do not create duplicate devices or products.

### Observability and Audit

- **`@OperateLog`** – Records operation metadata (module, action) to the audit log via the **admin** service.
- **`@TraceLog`** – Injects request-trace IDs for distributed tracing with Jaeger or Zipkin, primarily applied to pagination and detail queries.

## Integration Patterns for Microservices

When calling KCloud-Platform-IoT APIs from **another micro-service** (such as an API gateway or edge node), follow these patterns:

1. **Use Spring WebClient** (reactive) or **RestTemplate** (blocking) targeting the IoT service base URL.
2. **Propagate the JWT token** in the `Authorization` header obtained from the **auth** service.
3. **Serialize DTOs** exactly as defined in the source code—simple POJOs with Lombok getters/setters located in `laokou-iot-common`.

Example WebClient integration:

```java
WebClient client = WebClient.builder()
    .baseUrl("https://api.my-iot.com")
    .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token)
    .build();

Mono<Result<Page<DeviceCO>>> page = client.post()
    .uri("/v1/devices/page")
    .contentType(MediaType.APPLICATION_JSON)
    .bodyValue(new DevicePageQry(1, 20, "TempSensor"))
    .retrieve()
    .bodyToMono(new ParameterizedTypeReference<Result<Page<DeviceCO>>>(){});

```

## Key Source Files Reference

| Component | File Path | Direct Link |
|-----------|-----------|-------------|
| Device Controller | [`laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/DevicesController.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/DevicesController.java) | [View Source](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/DevicesController.java) |
| Device Service Interface | [`laokou-service/laokou-iot/laokou-iot-client/src/main/java/org/laokou/iot/device/api/DevicesServiceI.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-iot/laokou-iot-client/src/main/java/org/laokou/iot/device/api/DevicesServiceI.java) | [View Source](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-client/src/main/java/org/laokou/iot/device/api/DevicesServiceI.java) |
| Device Service Implementation | [`laokou-service/laokou-iot/laokou-iot-app/src/main/java/org/laokou/iot/device/service/DevicesServiceImpl.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-iot/laokou-iot-app/src/main/java/org/laokou/iot/device/service/DevicesServiceImpl.java) | [View Source](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-app/src/main/java/org/laokou/iot/device/service/DevicesServiceImpl.java) |
| Device DTOs | `laokou-service/laokou-iot/laokou-iot-client/src/main/java/org/laokou/iot/device/dto/` | [View Directory](https://github.com/koushenhai/kcloud-platform-iot/tree/master/laokou-service/laokou-iot/laokou-iot-common/src/main/java/org/laokou/iot/device/dto) |
| Product Controller | [`laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/ProductsController.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/ProductsController.java) | [View Source](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-service/laokou-iot/laokou-iot-adapter/src/main/java/org/laokou/iot/web/ProductsController.java) |
| Response Wrapper | [`laokou-common/laokou-common-i18n/src/main/java/org/laokou/common/i18n/dto/Result.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-common/laokou-common-i18n/src/main/java/org/laokou/common/i18n/dto/Result.java) | [View Source](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-common/laokou-common-i18n/src/main/java/org/laokou/common/i18n/dto/Result.java) |
| Pagination Wrapper | [`laokou-common/laokou-common-i18n/src/main/java/org/laokou/common/i18n/dto/Page.java`](https://github.com/koushenhai/kcloud-platform-iot/blob/main/laokou-common/laokou-common-i18n/src/main/java/org/laokou/common/i18n/dto/Page.java) | [View Source](https://github.com/koushenhai/kcloud-platform-iot/blob/master/laokou-common/laokou-common-i18n/src/main/java/org/laokou/common/i18n/dto/Page.java) |

## Summary

- **REST adapters** expose a clean, versioned API surface under `/v1/` with OpenAPI documentation.
- **Service contracts (`*ServiceI`)** keep business logic decoupled from HTTP transport concerns, enabling testability and reuse.
- **DTO-centric design** using Commands (`*Cmd`), Queries (`*Qry`), and Client Objects (`*CO`) ensures stable, language-agnostic payload contracts.
- **Cross-cutting annotations**—`@Idempotent`, `@OperateLog`, `@TraceLog`, and `@PreAuthorize`—handle infrastructure concerns automatically without polluting business code.
- **Import/export functionality** leverages EasyExcel or Apache POI for streaming Excel processing via multipart form data endpoints.

## Frequently Asked Questions

### How do I authenticate requests to KCloud-Platform-IoT APIs?

KCloud-Platform-IoT uses Spring Security with JWT tokens issued by the **auth** service. You must include an `Authorization: Bearer <token>` header where the token contains authorities like `iot:device:save`. Controllers validate these using `@PreAuthorize` annotations that check for specific permission strings.

### What is the difference between Cmd and Qry DTOs in KCloud-Platform-IoT?

**Cmd (Command) DTOs** such as `DeviceSaveCmd` represent write operations that modify state, while **Qry (Query) DTOs** like `DevicePageQry` represent read-only operations. This Command Query Responsibility Segregation (CQRS) pattern separates the data structures for creating resources from those for searching or filtering, allowing the API to evolve independently for reads versus writes.

### How does KCloud-Platform-IoT prevent duplicate API submissions?

The platform uses the `@Idempotent` annotation on controller methods to prevent duplicate submissions. This implementation uses either token-based verification or Redis distributed locks to ensure that retries due to network timeouts do not result in duplicate device registrations or product modifications.

### Can I integrate KCloud-Platform-IoT APIs from non-Java services?

Yes, the APIs are standard HTTP/JSON endpoints. While the DTOs are defined as Java classes in `laokou-iot-common`, they are simple POJOs that serialize to predictable JSON structures. Any client capable of making HTTP requests and parsing JSON—including Python, Node.js, or Go applications—can interact with the endpoints by replicating the field structures found in the source DTO files.