ARI REST Requests over WebSocket

Development
1

I’m working on implementing the ability to submit ARI REST requests over the same websocket you receive events on and need some feedback…

The protocol used is SwaggerSocket and while that github repo is archived, the protocol itself is dead simple JSON wrappers and the lightest I could find.

Sample request:

{
  "identity": "voicebot",
  "requests": [
    {
      "uuid": "9c3df4c6-1c5d-4fde-bee9-a27999334ccd",
      "method": "GET",
      "path": "channels/dummy-1741814579.0"
    }
  ]
}

Technically, SwaggerSocket allows making multiple requests in the same message (hence requests is an array) but we’re only going to support a single request per message for now.

Sample response:

{
  "type": "RESTResponse",
  "timestamp": "2025-03-12T15:22:59.227-0600",
  "asterisk_id": "e4:1d:2d:b8:3b:a0",
  "application": "voicebot",
  "identity": "voicebot",
  "responses": [
    {
      "uuid": "9c3df4c6-1c5d-4fde-bee9-a27999334ccd",
      "statusCode": 200,
      "reasonPhrase": "OK",
      "path": "channels/dummy-1741814579.0",
      "headers": [],
      "messageBody": {
        "id": "dummy-1741814579.0",
        "name": "PJSIP/alice-00000000",
        "state": "Ring",
        "protocol_id": "1-1339012@127.0.0.2"
        "caller": {
          "name": "8005551212",
          "number": "8005551212"
        },
        "connected": {
          "name": "",
          "number": ""
        },
        "accountcode": "",
        "dialplan": {
          "context": "default",
          "exten": "1118",
          "priority": 2,
          "app_name": "Stasis",
          "app_data": "voicebot"
        },
        "creationtime": "2025-03-12T15:22:59.225-0600",
        "language": "en_US"
      }
    }
  ]
}

The response itself is a new ARI Event type “RESTResponse” and the responses.messageBody is the same response you’d get from a HTTP GET. The uuid you supplied on the request will be returned in the response so you can correlate the two which is important since you may get normal events between sending the request and getting the response.

Here’s the question… Since messageBody could be any ARI object that could get returned from the equivalent HTTP call and getting our Swagger implementation to support the “oneOf” construct isn’t going to happen any time soon, how will this affect your implementation? Right now, these events are not included in the generated Swagger docs for that reason. Would you rather have messageBody just be a string containing escaped JSON for you to unmarshall or left as a real JSON object? If defined as a string, then the event can be integrated into the Swagger stuff. If left as an object, it’ll be up to you to handle the event but at least it will still have the fields common to all events.

And another question for my testing efforts… Which languages are you using for ARI and which packages, if any, are you using to unmarshall events?

I’m thinking I’ll have a draft PR and some documentation up on the website sometime next week.

1 Like