Definition
RESTful refers to the HTTP-based REST architectural style, using standard methods such as GET/POST/PUT/DELETE to operate resources. The Device Management Platform provides device management, data query, OTA deployment, and other capabilities via the RESTful API, and, when combined with the OpenAPI specification, facilitates third-party system integration.
Design Principles and Standards
RESTful emphasizes resource-oriented URLs (e.g., /devices/{id}), statelessness, and a uniform interface. GET is used for queries, POST for creation, PUT/PATCH for updates, DELETE for deletion; status codes (200, 201, 400, 404, 500) indicate operation results. Device Management Platform APIs typically use a version prefix (e.g., /v1/devices), pagination parameters, filtering, and sorting, supporting JSON requests/responses. In combination with the OpenAPI (Swagger) specification, it is possible to automatically generate documentation, SDKs, and Mock services.
Typical Interfaces with DMP
The platform's RESTful API covers device CRUD, batch queries, OTA task creation and querying, alarm and event subscriptions, telemetry data aggregation, and more. Third-party systems (such as ERP, EAM, BI tools) can use the API to fetch device status, operational metrics, or send control commands. Authentication (OAuth2, API Key), rate limiting, and Audit Log auditing are required to ensure security and stability.
Use Cases
Suitable for system integration, automated operation and maintenance, data export, as well as mobile and third-party application integration. With standardization and mature ecosystem, RESTful has become the mainstream interface form for Device Management Platform external access.
How a resource identifier stays separate from the action
A REST-style API treats devices, groups, upgrade tasks, and alarms as resources. The identifier in the path locates them. The method expresses a read or a change. Queries use the retrieve method. Creation uses a submit. A full replacement and a partial update should not be the same unexplained action. A delete should point at a resource that already exists. When an action such as "restart the device" has to be forced into a resource path, model it as a task resource: submit one task, then retrieve the task status. Do not invent a verb path that has no way to represent a result.
Identifiers must be stable. A path built from a display name that changes with a note makes saved links fail. Pagination needs a stable order and a next-page marker. An offset alone is not enough: if creates and deletes happen while the caller is turning pages, the caller misses a device or sees the same device twice. Write filters in query parameters, and echo the filters that actually took effect in the response, so the caller does not believe the result was filtered by site while the server ignored an unknown parameter and returned everything. The error body should carry a machine-readable reason code, not only a sentence that changes with the version.
When an idempotent write may be retried
Whether a write may be retried after a network timeout depends on whether running it twice is equivalent to running it once. A create that carries an idempotency key supplied by the caller should return the first result on the second call, not open another upgrade task. A submit with no idempotency key leaves the caller, after a timeout, unable to know whether the task was created. A blind retry produces two tasks. The condition for use is therefore that every API which changes a device or a task accepts an idempotency key, and remembers the result for that key long enough.
A retrieve method should not have side effects. Some implementations treat "get device" as a chance to refresh online state or to record a business change outside the export audit. Retries and prefetching then change state. A read that must be audited should be an explicit export action, not an ordinary query in disguise. Authentication failure, insufficient permission, and a missing resource need different statuses. Do not report every failure as not found in order to hide whether the device exists. The integrator then cannot tell a bad key from a mistyped identifier. When rate limiting, say how long to wait before trying again. Do not simply drop the connection.
Putting a long task into a synchronous call
An upgrade, a bulk parameter change, and a wide export cannot wait until they finish inside one request. The connection times out first, the caller retries, and the server may still be doing the first attempt. The right split is to return a task identifier immediately after submit, to read progress from another retrieve API, and to notify completion or failure with an event notification. A synchronous API should keep only checks that truly finish inside a short limit, such as whether the parameters match the thing model.
Another common mistake is to carry a key in the query string, or to put the full data of the previous page into the next-page address. The key lands in access logs, and the full data makes the address long enough to be truncated. Put the key in a header. Pagination should carry only a position marker. Put the version in the path, and raise the version only for a change that breaks compatibility. Delete a field inside the same version and old callers discover the missing value only at runtime. If a response offers two time formats and does not state the time zone, reconciliation is off by a day at the boundary. The API description should fix one representation that includes the time zone.
Write the change record for the caller: which optional fields were added, which fields are still guaranteed to exist, and whether any error codes were added. A diff shared only internally means external systems meet a parse failure in production. For a submit that creates a task, return the task identifier and the path that queries it, so the caller does not have to guess how addresses are joined. State the default sort of a list API and keep it stable. If an unstated default sort changes, an integration that deduplicates by paging loses rows. Before a deprecated version is shut off, list the integrations still calling it, and take it down only after they have stopped. When a caller sees a new field it does not recognize yet, it should ignore that field and keep processing the fields it knows, rather than failing the whole payload. Write that compatibility rule into every version note, so an optional extension does not break every old system.