Push error field

[maratal]

Originated from ably/ably-cocoa#1268

Perhaps before we start trying to parse this field, we should get it added to the documentation for the "get details from a registered device" etc REST API endpoints?

(from here)

So, the issue point is that error field has no description in the docs:

Get details from a registered device
GET rest.ably.io/push/deviceRegistrations/deviceId
Returns
A JSON object like:

    {
      id: <string>,
      clientId: <optional, string>
      platform: <string>
      formFactor: <string>,
      metadata: <object>,
      updateToken: <string>,
      push: {
        recipient: {
          transportType: <string>,
          <additional recipient address key/value pairs>
        },
        state: <active or failed>
      }
    }

Also, in order to fix this in code with appropriate tests, a new device should be added similar to one with the id "testDeviceDetails" (f.e. "testFailedDeviceDetails") which would always return failed state with an error, so it can be properly tested. Currentlly tests request a device like that:

GET rest.ably.io/push/deviceRegistrations/testDeviceDetails

which always in an active state (without error field).

┆Issue is synchronized with this Jira Task by Unito

[ably-sync-bot]

➤ Tony Bedford commented:

{quote}So, the issue point is that error field has no description in the docs ( https://docs.ably.io/rest-api/#get-device-registration ):{quote}

Quintin Willison - are you able to provide the description that’s required here please? If so we can get it added to the docs. Thanks!

[QuintinWillison]

I just had a quick look at this, and it's a bit of a rabbit hole, with work unfinished in the SDK which may change the outcome (e.g. ably/ably-cocoa#1269). I'm going to assign this issue to @maratal so they can see it home once the SDK work is done.

[maratal]

@tbedford Here instead of:

    {
      id: <string>,
      clientId: <optional, string>
      platform: <string>
      formFactor: <string>,
      metadata: <object>,
      updateToken: <string>,
      push: {
        recipient: {
          transportType: <string>,
          <additional recipient address key/value pairs>
        },
        state: <active or failed>
      }
    }

it should be:

    {
      id: <string>,
      clientId: <optional, string>
      platform: <string>
      formFactor: <string>,
      metadata: <object>,
      updateToken: <string>,
      push: {
        recipient: {
          transportType: <string>,
          <additional recipient address key/value pairs>
        },
        state: <active or failed>,
        error: {
          code: <string>,
          statusCode: <string>,
          message: <string>
        }
      }
    }

Also, in addition to "or a 404 error if a device by that ID does not exist." brief description of push.error field should be added:

or a 404 error if a device by that ID does not exist. push.error contains error information in case if Ably couldn't register device properly on a behalf of push notifications provider.

@QuintinWillison @lawrence-forooghian

[sync-by-unito]

➤ Automation for Jira commented:

The link to the corresponding Jira issue is https://ably.atlassian.net/browse/SDK-2763

[maratal]

Docs have changed a lot since my previous comments on this, now the page about the device registrations contains information about errorReason. But still its name is invalid and should be just an "error" in according to the server response, as demonstrated in this comment