API Developer Feedback Needed on API Change

BETA BETA API
1

We’re working on support for several technologies of 2-way motors. The motors sometimes take a while to respond, so we cannot wait for their reply before responding to the API client’s action request. So, we are thinking of doing the following:

  1. Client makes the action request as usual:
curl -iH "Bond-Token: xxx" bondip/v2/devices/x/actions/Open -x PUT -d {}
  1. Today, the reply you get is:
HTTP/1.1 200 OK
Connection: close
BOND-Flags: 132
Content-Length: 34
Content-Type: application/json; charset=utf-8

{"_":"00000000","__":"00000000"}

I’m proposing that—only for devices that support 2-way communication—you get:

HTTP/1.1 200 OK
Connection: close
BOND-Flags: 132
BOND-UUID: aabbccdd11223344
Content-Length: 34
Content-Type: application/json; charset=utf-8

{"_":"00000000","__":"00000000", "_status": "pend"}

And then you can get updated action status by either listening on BPUP (or MQTT for the Bond Home app), or by polling the same HTTP endpoint but using the specified request ID:

curl -iH "Bond-Token: xxx" -H "BOND-UUID: aabbccdd11223344" bondip/v2/devices/x/actions/Open -x PUT -d {}

If you choose to poll, an interval of 300 ms is recommended, with a 7 sec timeout. Note that these subsequent requests do not generate new RF signals because the Bridge caches the request by UUID and will not take action twice for the same UUID. It’s just a way to get an update on the request.

The values for _status are:

  • pend — request is waiting to be sent by the Bridge
  • sent — request has been sent to the device, waiting for a reply
  • ack — request has been acknowledged by the device
  • nack — device rejected the request for some reason
  • timeout — Bridge did not get a reply from the device in the allotted time window, but the request may have been received (technology specific, but never more than 7 seconds)
  • fatal — many attempts were made to communicate with the device, but they have all failed

Our intention with this is two-fold:

  1. Not to break any existing implementation. (For this reason we avoid using 202 Accepted as we had previously proposed.)

  2. To allow all UIs to show a happy indicator to a user when we get ack. Note that we expect there to be many cases where the uplink is not as reliable as the downlink, so we recommend against showing a user-facing error for every timeout, only showing an error on fatal and nack status.

We will also usually have a signal strength reading, and battery feedback if applicable, but those are just normal fields on the API. The above is the tricky part for us to get right. Your feedback is appreciated.

1 Like
2

A return of “Pend” or “Queued” makes sense.
Not sure if ALL platforms are currently handling Headers in return messages?
So is it possible to belt-and-suspender it, returning the BOND-UUID: aabbccdd11223344 in data payload in addition to the header? Or is that violating a design standard or stance?

This part sounds good to me as-is, but my integrations are pretty unique to my use cases.

Would love to hear other plugin / public integration developers chime in about this overall - thanks @merck and team for soliciting feedback from your community!