sromocki | 2016-10-12 14:33:18 UTC | #1
Hello Purecloud API Team,
We have noticed a recent change regarding case of Enums in the notification responses for the conversations topic, but do not see corresponding changes in the API. The previous notifications were upper case but now they have been changes to lower case as seen below:
Previous:
"calls": [ { "state": "DISCONNECTED", "recording": false, "recordingState": "NONE", "muted": false, "confined": false, "held": false, "disconnectType": "TRANSFER", "direction": "INBOUND", "self": { }, "other": { }, "connectedTime": "2016-08-30T19:06:10+0000", "disconnectedTime": "2016-08-30T19:06:12+0000", "disconnectReasons": [ { "type": "SIP", "code": 410, "phrase": "Gone" } ], "additionalProperties": {} } ]
Current:
{ "id": "285f8cd5-f713-4b96-988c-8f857ba5f891", "state": "disconnected", "recording": false, "recordingState": "none", "muted": false, "confined": false, "held": false, "disconnectType": "transfer", "direction": "inbound", "self": { }, "other": { }, "provider": "Edge", "connectedTime": "2016-10-11T20:31:08+0000", "disconnectedTime": "2016-10-11T20:31:33+0000", "additionalProperties": {} }
The API expects that these are upper case, so we are adding a code change to make sure they are always upper case. We thought we'd bring this to your attention since we think they should probably be consistent.
Thank you, Sean Romocki
tim.smith | 2016-10-11 21:58:16 UTC | #2
The change to lower case was intentional as the upper case values were a bug. API-2013 has been created to update the documentation for notifications to indicate the correct (lower case) enum values. CS-691 has been created to update the API docs.
sromocki | 2016-10-11 22:21:29 UTC | #3
Ok sure. Couple of curious questions.
1.) Why was the upper case value a bug? Seemed to work fine for us til yesterday.
2.) Is CS-691 responsible for tracking the change to the API to use lower case values?
3.) Is there documentation for notification events? If not, we were looking to know at least the expected values for the calls array inside the conversation returned in the events. Would be helpful to know whether we need null checks or not, etc..
tim.smith | 2016-10-12 15:20:49 UTC | #4
Why was the upper case value a bug?
All enums are supposed to be lower case in v2 and there were some non-conforming resources.
Is CS-691 responsible for tracking the change to the API to use lower case values?
No, that's for updating the documentation for the API to document the correct values.
Is there documentation for notification events?
Yes, see the Notifications API category: https://developer.mypurecloud.com/api/rest/v2/notifications/index.html
sromocki | 2016-10-13 15:02:40 UTC | #5
I see the schema for the available topics which is very helpful. Although it would be nice to eventually have some kind of indication for required fields, so we don't have to null check everything.
tim.smith | 2016-10-13 15:25:57 UTC | #6
I've created API-2016 to look into adding some notation for required/optional. Most of the notification schemas are reused from the related API requests though. So you can compare a notification schema to an API request that gives you the same data. If the schemas match up, it's relatively safe to assume that the optional/required notation on the API schema will be adhered to for the notification. However, it's generally a coding best practice for an application to protect itself against missing values regardless of if a value is supposed to be required or not.
tim.smith | 2016-10-17 14:25:37 UTC | #7
Just an update on this, API-2016 is being closed. The notification events may send all documented properties, or they may send only the properties that change. That determination is made by the sending service, which is why it may be different per event. Because of this, the current issue is being closed. However, we are taking this feedback into consideration for future enhancements to the notifications.
system | 2017-08-28 19:27:55 UTC | #8
This post was migrated from the old Developer Forum.
ref: 495