Re: [asterisk-dev] ARI Text messaging : inconsistencies in the API ?
On Tue, Feb 25, 2020 at 4:43 AM Jean Aunis 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
--
_
-- Bandwidth and Colocation Provided by http://www.api-digital.com --
asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/asterisk-dev
Re: [asterisk-dev] ARI Text messaging : inconsistencies in the API ?
Le 25/02/2020 à 19:09, Kevin Harwell a écrit :
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?
I agree with option "C".
--
Kevin Harwell
Software Developer
Sangoma Technologies
Check us out at: https://sangoma.com
[asterisk-dev] ARI Text messaging : inconsistencies in the API ?
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 ?
Regards,
--
Jean AUNIS
Ingénieur R
R engineer
Tel : +33 1 30 85 90 22
Standard: +33 1 30 85 55 55
Rue de Broglie
22300 LANNION
FRANCE
www.prescom.fr
