Preecha

Posted on Apr 22

API Platform for IoT Development

#api #iot #testing #tooling

TL;DR

IoT APIs have unique requirements: limited bandwidth, binary payloads, device-focused authentication, and non-HTTP protocols. This post explains what IoT developers need from API tools, where standard tools like Apidog fit, where they don’t (like MQTT), and how to test the HTTP-facing layer of your IoT backend.

Try Apidog for Free

Introduction

IoT development involves two main API layers. Device-facing protocols (MQTT, CoAP, custom binary, WebSocket) focus on efficiency for constrained devices and networks. Platform-facing APIs (REST) handle provisioning, firmware updates, telemetry ingestion, and management dashboards.

Most API tools only cover the platform-facing REST layer—not device protocols like MQTT. Don’t expect a standard API platform to handle MQTT natively. The best approach: use standard API tools for HTTP/WebSocket, and specialized tools for MQTT or CoAP.

This article maps IoT protocol needs, shows what Apidog covers, and provides actionable steps for testing the HTTP layer of your IoT backend.

The IoT Protocol Landscape

MQTT: Core protocol for device-cloud messaging

MQTT is the main protocol for device-to-cloud communication. Designed for unreliable, bandwidth-limited environments, it uses a publish/subscribe model with topics, QoS, retained messages, and LWT.

Apidog does not support MQTT natively. For MQTT testing, use:

MQTT Explorer: Desktop GUI for broker/topic inspection
MQTTX: Cross-platform GUI and scripting
mosquitto_sub/mosquitto_pub: CLI tools from Mosquitto
HiveMQ Broker: Free tier with web client

Tip: Always plan for a dedicated MQTT tool alongside your HTTP API tool.

HTTP/REST: Managing devices and data

Every IoT platform exposes REST APIs, even if devices use other protocols for telemetry. Typical REST use-cases:

Device provisioning: Registration, cert creation, identity assignment
OTA firmware updates: Check for and deliver firmware
Configuration: Push new settings to devices/groups
Telemetry ingestion: Many accept HTTP POST telemetry
Device management: Fleet status, remote commands, grouping
Data queries: History, logs, alerts
Webhook setup: Outbound event notifications

REST APIs are fully testable with tools like Apidog.

WebSocket: Real-time bidirectional communication

WebSocket bridges the gap between REST and MQTT for real-time, two-way messaging:

Device command streams
Live telemetry updates to dashboards
Bidirectional config updates

Apidog supports WebSocket testing, including custom connection headers for most IoT scenarios.

CoAP: For the most constrained devices

CoAP is an HTTP-like protocol for microcontrollers and tight bandwidth constraints, running over UDP.

Not supported by Apidog. Use:

copper4cr: Browser extension
libcoap: CLI tools

Binary Payloads

IoT devices often use binary encodings (Protocol Buffers, MessagePack, CBOR, or custom formats) instead of JSON.

Apidog allows raw binary HTTP request bodies, supporting hex or base64-encoded payloads for platforms that accept binary over HTTP.

Device Authentication Patterns in IoT

IoT device auth differs from standard web API auth. While OAuth2 and API keys are supported by most tools, IoT adds:

Mutual TLS (mTLS)

Cloud IoT platforms (AWS, Azure, Google) use mTLS for device authentication. Each device has a client certificate.

Testing mTLS in Apidog:

Load device certificate and private key in SSL settings
Connect to endpoints requiring mTLS authentication

Device-specific API Keys

Some platforms issue per-device keys or token pairs. Use as Bearer tokens or API key headers—Apidog handles both.

JWTs with Device Claims

Platforms may issue JWTs with device info. Use Bearer auth; handle token refresh via pre-request scripts if needed.

Custom Header Auth

Some platforms use proprietary headers (e.g., X-Device-Token). Apidog supports arbitrary custom headers.

Testing IoT REST APIs with Apidog

Device Provisioning Flows

Provisioning usually involves multiple REST steps:

POST device registration (serial, model, firmware)
Receive device ID/credentials in response
Configure device with credentials
GET to verify registration

Implementation:

Use chained requests in Apidog
Extract device ID with a post-request script and set as environment variable
Use the variable in subsequent requests for full flow automation

OTA Firmware Update Endpoints

Common OTA steps:

GET /devices/{id}/update-check
GET /devices/{id}/firmware
POST /devices/{id}/update-status

Test with Apidog:

Inspect firmware binary responses (headers, content)
Validate correct download and reporting flows

Telemetry Ingestion (HTTP)

Many platforms accept telemetry as HTTP POST, often in binary.

To test binary ingestion:

Set body type to raw
Choose binary format
Paste hex or base64-encoded payload
Set Content-Type: application/octet-stream (or required type)
Send and check response

Protobuf: Encode test payload with your language’s protobuf library, then paste the binary.

SSL Certificate Testing

IoT backends often use self-signed or pinned certs.

Apidog SSL settings let you:

Disable SSL verification for dev/self-signed certs
Load custom CA for private deployments
Load client certificate for mTLS

WebSocket Testing for IoT Device Streams

Common real-time use-cases:

Device shadow/twin updates (AWS IoT, Azure IoT)
Live telemetry to dashboards
Command delivery to devices

Test with Apidog:

Connect using required auth headers (Bearer/API key)
Send subscription messages if needed
Monitor incoming messages
Send test commands and observe device response
Specify subprotocols via Sec-WebSocket-Protocol if required

What to Use for MQTT Testing

Since Apidog doesn’t support MQTT:

MQTTX: Full-featured GUI, scripting, TLS/mTLS, all protocol versions
MQTT Explorer: Visualize topic trees and broker state
mosquitto_pub/sub: CLI tools for quick, scripted tests
CI/CD: Use language-native MQTT libraries (e.g., paho-mqtt for Python, MQTT.js for Node)

Practical IoT Backend Testing Setup

Environment configuration:

Environments:
  local-dev:
    base_url: http://localhost:8080
    ssl_verify: false
  staging:
    base_url: https://iot-staging.example.com
    ssl_verify: true
  prod:
    base_url: https://api.iot.example.com
    ssl_verify: true

Variables:
  device_id: dev_test_001
  device_serial: SN-TEST-00001
  auth_token: {{fetched via pre-request script}}
  firmware_version: 2.1.4

Folder structure:

- provisioning/         # Registration/credential flows
- telemetry/           # Ingestion endpoint tests (JSON, binary)
- ota/                 # Firmware update flows
- device-management/   # Device CRUD operations
- websocket/           # Real-time stream tests
- error-cases/         # Invalid/malformed tests

Binary payload test checklist:

Valid binary payload
Truncated/incomplete payload
Wrong Content-Type
Max-size payload
Correct/incorrect auth

FAQ

Does Apidog support MQTT testing?

No. Use MQTTX, MQTT Explorer, or mosquitto CLI for MQTT. Apidog covers HTTP and WebSocket, not MQTT.

Can Apidog test CoAP endpoints?

No. CoAP is UDP-based; use copper4cr or libcoap.

How to test binary protobuf payloads in Apidog?

Encode with your protobuf library, convert to hex/base64, paste into raw binary body, set appropriate Content-Type.

Does Apidog support mTLS/device certificate authentication?

Yes. Load client cert and key in SSL settings.

Can Apidog test AWS IoT, Azure IoT Hub, or Google Cloud IoT?

Yes—for their HTTP/REST APIs. Use MQTTX for MQTT connections.

Best approach for low-bandwidth binary telemetry testing?

Create test fixtures (valid, truncated, malformed payloads), store as environment variables or files, send via Apidog, check responses.

No single tool covers every IoT protocol. Use Apidog for HTTP/WebSocket (provisioning, management, telemetry, binary, mTLS), and MQTTX/mosquitto for MQTT. Knowing when to use which tool is key to efficient IoT development.

DEV Community