[asterisk-dev] ARI Text messaging : inconsistencies in the API ?

[Kevin Harwell]

On Tue, Feb 25, 2020 at 4:43 AM Jean Aunis <jean.aunis at prescom.fr> wrote:

> Hello,
>
> I recently opened a issue regarding SIP headers handling in inbound
> messages (https://issues.asterisk.org/jira/browse/ASTERISK-28755).
>
> Besides that problem, I think there are inconsistencies in the data format
> provided by ARI for sending or receiving text messages, and also in the
> documentation. Actually there are 3 different data formats for message
> variables:
>
> 1- to send a message, additional variables may be provided in a
> "variables" field. Its value must be a JSON object whose keys are the
> variable names, and values are the variable values, i.e:
>
> ...
> "variables": { "My-Custom-Header": "the_value", "Another-header":
> "another_value" }
>
> 2- when a message is received, a TextMessageReceived is emitted, which
> contains a TextMessage which then contains a "variable" field. This field
> is a list of JSON objects, each one containing a single key (the variable
> name) with its value :
>
> ...
> "variables": [{ "My-Custom-Header": "the_value" }, { "Another-header":
> "another_value" }]
>
> (This is what I saw after quick-fixing the issue stated above)
>
> 3- the behaviour described in (2) is not consistent with the ARI
> documentation, which states:
>
> TextMessageVariable: A key/value pair variable in a text message.
>
>     key: string - A unique key identifying the variable.
>     value: string - The value of the variable.
>
> So I would expect the variable field to look like the following:
>
> ...
> "variables": [{ "key": "My-Custom-Header", "value": "the_value" }, {
> "key": "Another-header", "value": "another_value" }]
>
> I personally think formats (1) and (3) both make sense, but I find format
> (2) not very practical to use. Any thoughts on the subject ?
>
I could never get (2). When trying to send variables in the
TextMessageReceived event I would get a validation error unless they are
formatted like (3).

(3) is the currently declared documented way to to it. As such any other
way breaks the API definition. However, when executing a sendMessage (1) is
the way it is currently working, so I'd be worried about breaking current
implementations if we altered it to (3) for that case.

So what to do?

Option A: Leave sendMessage as is (1), update the documentation for it, and
fix TextMessageReceived to send variables as defined like (3). Least
breaking, but inconsistent way of sending and receiving variables.

Option B: Update sendMessage to pass a TextMessageVariable like (3), and
fix TextMessageReceived to send variables like (3). The current API
definition doesn't change, but may break implementations.

Option C: Leave sendMessage as is (1), update the TextMessageVariable API
definition to be similar to (1), e.g { "var name": "var value" }, and not {
"key": "var name", "value": "var value" }. This of course breaks the
current API definition, and would break implementations if the validation
error did not occur.

While "A" is the safest (least breaking?), personally, I prefer and choose
"C". While it does break the API it seemingly has not worked since the
start so I don't think this will break any current implementations. It will
also make sending and receiving variables more consistent.

Thoughts?

-- 
Kevin Harwell
Software Developer
Sangoma Technologies
Check us out at: https://sangoma.com & https://asterisk.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20200225/2687eef6/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: acdablmkfjjojald.png
Type: image/png
Size: 5275 bytes
Desc: not available
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20200225/2687eef6/attachment.png>