SSAP Protocol Improved



In this post we present a new version of Sofia 2 SSAP interoperability protocol, what advantages brings and how to start using it. We also show how Sofia 2 keeps the compatibility with former versions in order to keep current clients working without any modification needed.

The main news are listed below:

  1. JSON navigation improvement. Thanks of changes in datatypes of two attributes in JSON Schema, usability and navigation of JSON strings have been improved. This fact makes easier integration with any JSON Libray of any programming language.
  2. Attribute version added. Tells the SSAP version of the current message, it’s also used to tell Sofia 2 the required version for response messages. The available versions are:
    1. LEGACY: SSAP reference until now
    2. ONE: New reference
  3. Attribute @type added. Tells the operation type stored in body attribute.

Protocol Description

In previous posts we presented the SSAP interoperability protocol in this way: Meeting SSAP protocol


“body”: “”,
“messageId”: “”,
“sessionKey”: “”,
“ontology”: “”,
“direction”: “”,
“messageType”: “QUERY”

New SSAP version format (differences are highlighted in blue)

ONE Formato (new)

“body”: {
      “@type”: “”,
      “data”: {},
      “version”: “[LEGACY|ONE]”
“messageId”: “”,
“sessionKey”: “”,
“ontology”: “”,
“direction”: “”,
“messageType”: “QUERY”,
“version”: “[LEGACY|ONE]”

Body attribute

The biggest difference between versions ONE and LEGACY resides in body attribute. In this new version the body attribute type has been changed from string to JSON Object. In the same way the type of attribute data is JSON Object. Thanks to these two data types changes now it is possible to serialize and navigate through the whole JSON structure in this way: ssap_message->body->data.attribute1->subattribute1. In former versions this navigation was also possible, but several serializations were needed, so this version represents an improvement in usability and performance.

Data attribute

In this new version, attribute data with type JSON Node has been added inside the JSON Schema. In previous version data attribute were embeded in body as a String. This change contributes to navegability improvement explained in the previous section.

Version attribute

This attribute represents the SSAP protocol version is used in communication with Sofia2.

Requests to Sofia2 with no version attribute are interpreted as LEGACY version, in this way exiting client applications will keep working without any updates or modifications.

There are two options to work with SSAP version ONE:

  1. Add version attribute in all requests to Sofia2
  2. Add version attribute in JOIN request to Sofia2. The response to this message is a sessionKey hash code. Further requests made with this sessionKey will get version ONE response.

@Type attribute

In order to make easier content message serialization/deserialization, response messages from Sofia2 include a new attribute called @type. This attribute can be found inside body.

When working with SSAP version ONE all Sofia2 responses include this new attribute. @type attribute is optional in request messages to Sofia2 thanks to sofia2 type inference engine.

This a list of message types availables:

  • SSAPBodyCommandMessage
  • SSAPBodyConfigMessage
  • SSAPBodyErrorMessage
  • SSAPBodyJoinMessage
  • SSAPBodyJoinTokenMessage
  • SSAPBodyJoinUserAndPasswordMessage
  • SSAPBodyLeaveMessage
  • SSAPBodyLocationMessage
  • SSAPBodyLogMessage
  • SSAPBodyOperationMessage
  • SSAPBodyQueryMessage
  • SSAPBodyQueryWithParamMessage
  • SSAPBodyQueryMessageQuasar
  • SSAPBodyReturnMessage
  • SSAPBodyStatusMessage
  • SSAPBodySubscribeCommandMessage
  • SSAPBodySubscribeMessage
  • SSAPBodyUnsubscribeMessage
  • SSAPBodyEmptyMessage
  • SSAPBodyBulkMessage

Test new SSAP version


Go to Sofia2 Api Rest playground through this url If you already don’t know this Sofia2 feature you can find an explanation in this post Meeting Sofia2 RESTFul Api

The only difference with previous usage is that JOIN request message must have a version attribute with value ONE

{“join”: true,”instanceKP”: “:”,”token”: “”, “version”:”ONE”}

You can use Sofia2 demo credentials to play around:

  • test.officials.token=49622ff059364fcea6ce78e8b0fa8b4b
  • test.officials.kp_instance=KP_APITesting:KPTestTemperatura01

 API Manager

The API manager feature has been updated so that all requests and responses are made with SSAP version ONE by default. If you already don’t know thos feature you can find an explanation in this post Api Rest Api Manager.


Download Sofia2 API JAVA from git and run tests or examples. Test source code is a good way to view usage examples. You can see a step by step HOWTO following the next post Client execution guide.

SSAP Protocol Improved

Un comentario en “SSAP Protocol Improved


Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de

Estás comentando usando tu cuenta de Cerrar sesión /  Cambiar )

Google photo

Estás comentando usando tu cuenta de Google. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s