[asterisk-app-dev] Event naming conventions

[Alistair Cunningham]

On 21/10/13 10:56, David M. Lee wrote:
> On Oct 21, 2013, at 8:09 AM, Alistair Cunningham <acunningham at integrics.com> wrote:
>
>> When I now check this page:
>>
>> https://wiki.asterisk.org/wiki/display/AST/Asterisk+12+REST+Data+Models
>>
>> I see no mention of Answer or Hangup. Have these already been removed, or am I looking on the wrong page?
>
> That's the right page.
>
>> I must confess that I'm not quite sure where to look on the Wiki for information about the websocket events. Is the "Data Models" page the same as the "Events" page? Matt showed me the correct place, but I foolishly failed to bookmark it. Apologies for the confusion…
>
> No worries… it's new for everyone.
>
> The "_ REST API" pages all of the basic structure. It leads off with a summary table, with HTTP method, URI path, return model (what you can expect as a response to the call) and a short summary of the operation.
>
> The "Path" column links further down the page where you can find more details about the operation (longer description, operation parameters, etc.).
>
> The "Return Model" column links into the "REST Data Models" page, where the return model schema is documented.
>
> The /events WebSocket is a bit wonky, because it can return many different types of messages.
>
> The way the model is structured, the 'Message' return model is actually a base-type for all of the events that could come over the /events WebSocket. If you click the 'Message' link, it will take you to the docs for that type, where all of the subtypes for Message are listed. That doc also tells you that the 'type' field in 'Message' is used as the discriminator, so you can tell what type of event you actually received.
>
> While this all seems very clear to me, I'm the one who wrote it :-D
>
> Suggestions for clarifying the wiki docs are gladly welcomed.

Thank you for explaining; that makes sense. It might be worth adding a 
note to the top of the page explaining to others who stumble upon it 
that this page does contain the events they'll receive. It may even make 
sense to have a dedicated "events" page whose URL makes it clear that it 
explains the websocket events.

-- 
Alistair Cunningham
+1 888 468 3111
+44 20 799 39 799
http://integrics.com/