2. Home
  4. Docs
  6. IoTGtw API Specification
  8. IoTGtw APIs
  10. Provisioning API

Provisioning API

The provisioning APIs allows registered accounts and underlying service components to be managed. The provisioning endpoints are described in the table below.

The following HTTP verbs (Operations) are interpreted as follows:

  • POST = CREATE
  • GET = RETRIEVE
  • PUT = UPDATE
  • DELETE = REMOVE

Please note that we are in the process of improving this API documentation for ease of use.

 

 

Provisioning API Endpoints Description Operation Permitted
/serviceTemplates Retrieve the full list of service templates created on the customer account. GET
/serviceTemplates/{service_template_id} Manage a specific service template on the customer account. GET, PUT, POST, DELETE
/serviceTemplateDevices/{service_template_id} Retrieve the full list of devices that are associated to a specific service template POST
/ServiceAccessPoints Retrieve the detailed list of all ServiceAccessPoints that are available to the customer account. GET
/ServiceAccessPoints/{service_access_point_name} Retrieve the details of a specific ServiceAccessPoint available to the customer account by specifying the service_access_point name GET
/messagingEndpoints Retrieve the detailed list of configured customer upstream endpoint configuration profile. GET
/messagingEndpoints/{messaging_endpoint_profile_id} Retrieve the details of a specific customer endpoint profile by specifying the customer endpoint profile id. GET, PUT, POST, DELETE
/devicesRetrieve Retrieve a shallow or detailed record of devices created on the customer account. The device record will include provisioned device data. For devices that support SimplyTiny the device record will also include last seen operational device data such as Device IP address, Device Port, Geo Location, Power Usage Stats,  Signal Strength, Connection, Disconnect, Last Activity timestamps, etc.

For example:

  • Retrieve all Devices created on the customer account (paginated)
  • Retrieve all Devices but limit each device record to specified fields only (capped)
  • Retrieve specific device(s) by their Unique Device ID (UDID)
  • Retrieve specific device(s) by their International Mobile Subscriber Identity (IMSI)
  • Retrieve specific device(s) by their custom Device Identifier (device_id)
  • Retrieve specific device(s) by their device_ip (Last seen Device IP. The service template ID of the device must also be supplied).
  • Retrieve list of devices that match specific conditions (status, device_ip, device_port, gps-coordinates, signal_strength, power_usage_stats,  )
  • Retrieve devices whereby either last_activity, last_wakeup, connection_time, disconnection_time timestamp (isoDate) are between the specified start and end date
 POST
/devicesUpdate This endpoint is used to create and or update the Devices on the customer account. As follows:

  • Create one or more Devices by supplying an array of device objects with a POST request operation
  • Update one or more Devices by supplying an array of device objects with a PUT request operation

Please refer to the sample API section for detailed examples of create and update device operation.

 POST, PUT
/devicesDelete Delete one or more device(s) by supplying an array list of either: Unique Device ID (UDID) or International Mobile Subscriber Identity (IMSI) or custom Device Identifier (device_id) POST
/accountDetails Used to retrieve and or update the customer account details information GET, PUT
/regions Used to retrieve the list of service regions and their associated API-Gateways and Socket-Gateways for UDP and TCP integrations GET
/count Provides a simple but powerful device and message queue analysis with multiple levels of filtering.

The main filter criteria parameter is the count_operation.

  • count_operation (required)
    Specify the type of count analytics operation required. From the enum:

    • “devices” – Perform the count analytics on the customer device objects (no message count involved)
    • “all_queues” – Perform count analytics on the pending queue, shipped queue and failed queue.
    • “pending” – Perform count analytics on the pending queue (this is the queue where the yet to be shipped messages are held).
    • “pending_uplink” – Perform count analytics on the pending queue but only count messages of delivery_type uplink.
    • “pending_downlink” – Perform count analytics on the pending queue but only count messages of delivery_type downlink.
    • “shipped” – Perform count analytics on the shipped queue (this is the storage queue where the sent messages are held).
    • “shipped_uplink” – Perform count analytics on the shipped queue but only count messages of delivery_type uplink.
    • “shipped_downlink” – Perform count analytics on the pending queue but only count messages of delivery_type downlink.
    • “failed” – Perform count analytics on the failed messages queue (this is the storage queue where the expired messages or message that could not be sent are held).
    • “failed_uplink” – Perform count analytics on the failed queue but only count messages of delivery_type uplink.
    • “failed_downlink” – Perform count analytics on the failed queue but only count messages of delivery_type downlink.

 

Additional filter criteria can be added to further narrow down the analytics operation to a specific device / message identifier.

  • Service_template_id
    Filter the device or message count analytics operation by a specific service template id. For example, to only include all devices configured with the specified service template id in the count operation.
  • Service_access_point
    Applicable to message count only. Filter the message count operation by a specific SAP. For example, to count all messages that matches this SAP.
  • imsi – Applicable to message count only. Limit the queues/storage count operation to a specific device object identified by the specified imsi
  • udid – Applicable to message count only. Limit the queues/storage count operation to a specific device object identified by thespecified udid
  • device_id – Applicable to message count only. Limit the queues/storage count operation to a specific device object identified by the specified device_id
  • device_ip – Applicable to message count only. Limit the queues/storage count operation to a specific device object identified by the device’s IP address to use this search option the device service_template_id must also be specified.
  • start_date – Applicable to message count only. Specify to filter the count operation by the specified start date. An end date must be specified.
  • end_date – Applicable to message count only. Specify the end date. The time difference between start_date and end_date must be 7 days or less.

 

The platform can also be instructed to return a further breakdown (split count) by any combination of the following.

  • delivery_type
    Only accepts a Boolean value. Set to true to further break down the count operation result by delivery type (split count by uplink and downlink)
  • device_tx_protocol
    Only accepts a Boolean value. Set to true to further break down the count operation result by the device_tx_protocols in the message records i.e. tcp, udp, etc.
  • device_app_protocol
    Only accepts a Boolean value. Set to true to further break down the count operation result by the device_app_protocol in the records i.e. coap, raw, simplytiny, mqtt-sn, etc.
  • msg_submit_status
    Only accepts a Boolean value. Set to true to further break down the count operation result by the message submit status labels i.e. message_expired, message_dropped, completed, etc.
  • service_access_point and service_template_id
    It is possible to split the count by the list of service_access_point and or service templates. If either of these parameters are provided with the value set to true (Boolean).

 

This is the messaging analytics endpoint for performing various analysis related to the device messages. For example:

  • Analyse the total number of devices, group result by device state and service template
  • Count the total number of devices configured with the specified service_template_id group by device state
  • Count the total number of devices using a specified SAP
  • Analyse the total number of messages in the “pending” queue of all devices (or specific device)
  • Analyse the total number of messages in “all_queues” of all devices (or specific device)
  • Analyse the total number of messages in “all_queues” of all devices that were sent/received within the specified start and end date
  • Analyse the total number of messages in the “shipped” queue of a specific device that were sent/received within the specified start and end date.
  • Analyse the total number of messages that matches custom filter criteria.
 POST
/subscriptionPackages Retrieve a detailed list of service subscription packages, service add-ons available and indicates which of the available service subscriptions are currently active (subscribed to) on the customer account GET
/subscriptionSummary Retrieve a summary list of the current service subscriptions packages and add-ons active (subscribed to) on the customer account GET
Was this article helpful to you? Yes No

How can we help?