generated: '2026-08-11'
method: searched
source: https://www.cosmoplat.com/help/detail/304/1038
docs: https://www.cosmoplat.com/help/detail/304/1038
summary: >-
  Cross-cutting request/response semantics of the COSMOPlat IoT development platform API,
  read from the published reference and confirmed against the transcribed OpenAPI. The API
  is a Spring-style JSON API with zero-based page/pageSize pagination and an explicit
  {entityType, id} reference object on every foreign key. It publishes no idempotency
  contract, no request-id header, no versioning scheme and no rate-limit signalling.
authentication:
  style: not documented
  detail: >-
    The REST reference documents no Authorization header, API key, token parameter or
    signing scheme on any of its 26 operations. Only Content-Type appears in the Headers
    tables. Device-side credentials ARE documented (Device.credentialsType is one of
    ACCESS_TOKEN / X509_CERTIFICATE / MQTT_BASIC and Device.deviceCredentialsId holds the
    access token), and the MQTT surface documents enterprise-ID/secret, but the REST
    caller's own credential is not published.
  see: authentication/cosmoplat-authentication.yml
content_type:
  request: application/json
  request_note: Declared explicitly in the Headers table of every operation with a body.
  response: application/json
pagination:
  style: page-number
  request_params:
  - name: page
    in: query
    required: true
    description: 页数（从0开始）— page number, zero-based.
    example: '0'
  - name: pageSize
    in: query
    required: true
    description: 每页最大数量 — maximum records per page.
    example: '30'
  response_fields:
  - name: totalPages
    description: 总页数 — total number of pages.
  - name: totalElements
    description: 总条数 / 总记录数 — total number of records.
  - name: hasNext
    description: 是否存在下一条记录 — whether a further page exists.
  - name: data
    description: The array of records for this page.
  inconsistency: >-
    Pagination is passed in the query string on GET collection operations
    (getPageTbProductManage, getTenantDevicesnew, getRuleChains, getPageByTenantIdAndProductId,
    getDeviceTelemetryProfilePageByDeviceId) but in the JSON request body on the POST
    collection operations (postAlarmSettingPage, postAlarmByEntityTypeGetTenantAlarms). The
    same two names are used both ways.
filtering:
  style: flat query parameters
  examples:
  - operation: getTenantDevicesnew
    params: [productManageId, name, realName, nodeType, active]
  - operation: getPageTbProductManage
    params: [identifier, textSearch, strNodeType]
  free_text_param: textSearch
entity_references:
  shape: '{entityType: <CONSTANT>, id: <string>}'
  description: >-
    Every cross-entity reference — tenantId, productManageId, defaultRuleChainId,
    originator, and the entity's own id — is an object carrying a fixed entityType
    discriminator plus a string id, never a bare id. Documented constants observed:
    TENANT, DEVICE, TB_PRODUCT_MANAGE, RULE_CHAIN, ALARM, TB_PRODUCT_TELEMETRY_PROFILE.
  see: data-model/cosmoplat-data-model.yml
upsert_convention:
  keyword: merger
  description: >-
    Thing-model telemetry points are written with "merger" operations
    (postMergerTelemetryProfile, postDeviceTelemetryProfileMergerTelemetryProfileByDeviceId)
    documented as 保存/修改 — save-or-modify. This is the closest thing in the API to an
    idempotent write, but the reference does not state the merge key or the semantics on
    conflict.
timestamps:
  representation: epoch milliseconds as JSON number
  fields: [createdTime, lastActivityTime, startTs, endTs, ackTs, clearTs, ts]
  exception: The failure envelope's `timestamp` is an ISO 8601 string, not epoch millis —
    two representations coexist.
idempotency:
  supported: false
  detail: >-
    No Idempotency-Key header, no client-supplied request identifier, and no idempotency
    section anywhere in the reference. Retrying postDevice, postTbProductManage,
    postAlarmSetting or postRuleChain after a timeout has undefined effect. Both RPC
    operations (postRpcOnewayByDeviceId, postRpcTwowayByDeviceId) dispatch commands to
    physical equipment with no de-duplication contract, which is the highest-consequence
    instance of the gap.
  pointer_emitted: false
  pointer_note: >-
    No `type: Idempotency` pointer is wired into apis.yml. The rubric awards 9 points for
    a real idempotency contract and COSMOPlat has none; emitting the pointer for a
    Conventions file that documents its absence would be false credit.
request_tracing:
  supported: false
  detail: No request-id / correlation-id / trace header is documented on request or
    response.
versioning:
  scheme: none published
  detail: >-
    Paths carry no version segment. The reference is titled "OpenApi-线上" (OpenAPI —
    online) with no version number, and no deprecation or sunset policy is published.
  see: lifecycle/cosmoplat-lifecycle.yml
error_envelope:
  shape: '{status, message, errorCode, timestamp}'
  media_type: application/json
  rfc9457: false
  see: errors/cosmoplat-problem-types.yml
rate_limit_signalling:
  supported: not documented
  detail: No X-RateLimit-*, RateLimit-*, or Retry-After header is documented, and no
    quota is published.
  see: rate-limits/cosmoplat-rate-limits.yml
localization:
  reference_language: zh-CN
  detail: >-
    The API reference, all field descriptions and the error `message` values are published
    in Simplified Chinese only. The corporate site has an /en locale; the developer
    documentation does not.
gaps:
- id: no-idempotency
  detail: Publish an Idempotency-Key request header with a stated retention window,
    starting with the two RPC dispatch operations.
- id: no-request-id
  detail: Return a request identifier on every response so a caller can quote it in a
    support ticket.
- id: pagination-split-between-query-and-body
  detail: page/pageSize live in the query string on GET list operations and in the body on
    POST list operations. One placement would halve the client's special-casing.
- id: two-timestamp-representations
  detail: Entity timestamps are epoch millis; the error envelope timestamp is ISO 8601.
- id: docs-zh-only
  detail: No English API reference, though the marketing site ships an /en locale and the
    platform is deployed in more than twenty countries.
x-evidence:
- url: https://www.cosmoplat.com/help/detail/304/1038
  http_status: 200
  fetched: '2026-08-11'