Service Message

To communicate with Avid Platform services, sender must be able to
compose valid request message and read corresponding response. Request
and response messages are using JSON format.

Request

To send request to Avid Platform service, caller must know type, version
and realm of the target service. Also caller must know parameters of the
request message. Here is example of the request to the service:

1
2
3
4
5
6
7
8
9
10
{
  "serviceType": "avid.acs.calculator",
  "serviceRealm": "global.test",
  "serviceVersion": 3,
  "op": "add",
  "paramSet": {
    "num1": 5,
    "num2": 3
  }
}

In the given example request will go to the service having type
“avid.acs.calculator” of version 3, having realm “global.test”.
Operation to be invoked on this service is “add”. Parameters to be
passed to this operations are “num1”=5 and “num2”=3.

In general, request message has two pieces:

  • message itself;
  • context;

Message is JSON object. In future releases content type will be designed to allow any message type.
JSON message has following mandatory fields:

Field Name Type Description Is Required Default
serviceType string name of the target service true n/a
serviceRealm string realm of the target service true n/a
serviceVersion integer version of the target service true n/a
op string name of the operation to be invoked true n/a
paramSet object parameters to be passed in the request to operation false n/a

Context is JSON Object with parameters to be passed in the request to the service operation.

Message example:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "serviceType": "avid.acs.calculator",
  "serviceRealm": "global.test",
  "serviceVersion": 3,
  "op": "addInContext",
  "paramSet": {
    "add": {
      "num1": 2,
      "num2": 4
    }
  }
}

Context example

1
2
3
4
5
6
{
  "add": {
    "num1": 2,
    "num2": 4
  }
}

Request message context have special object “sender”, which is populated
automatically by Secure Gateway with the following data:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "sender": {
    "access": {
      "id": "8dbb4278-1204-4686-92cd-e373cba728d3",
      "gateway": {
        "id": "7b8eb0e5-738a-40f5-8515-6b5bf308db9d",
        "bal": "java 3.7.2.25_g2cc0a90-SNAPSHOT",
        "host": "acs-zone-black",
        "pid": 4624,
        "platformId": "black",
        "buildNumber": "3.7.2_25_g2cc0a90-1.x86_64",
        "environmentId": "black"
      },
      "service": {
        "id": "94662691-c1fa-4a5b-9a20-919cb0d5e427",
        "bal": "node.js 3.7.2",
        "host": "acs-zone-black",
        "pid": 5549,
        "platformId": "black",
        "buildNumber": "3.5.3_2_g70b0518-1.x86_64",
        "environmentId": "black"
      }
    }
  }
}

Response

In general response message has three pieces:

  • response message itself;
  • context;
  • error set;

Response message is JSON object. In future releases content type will be designed to allow any message type.
JSON response message has following mandatory fields:

Field Name Type Description Is Required Default
serviceType string name of the service which provided response true n/a
serviceRealm string realm of the service which provided response true n/a
serviceVersion string version of the service which provided response true n/a
resultSet object response object from the service false n/a

Error set is JSON array with structured errors returned as a result of service operation execution

Context is JSON Object with parameters

Response message example:

1
2
3
4
5
6
7
8
9
{
  "serviceType": "avid.acs.calculator",
  "serviceRealm": "global.test",
  "serviceVersion": 3,
  "op": "divide",
  "resultSet": {
    "quotient": 4
  }
}

Context example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
  "sender": {
    "access": {
      "id": "8dbb4278-1204-4686-92cd-e373cba728d3",
      "bal": "java 3.7.2.25_g2cc0a90-SNAPSHOT",
      "host": "acs-zone-black",
      "pid": 4624,
      "platformId": "black",
      "buildNumber": "3.7.2_25_g2cc0a90-1.x86_64",
      "proxyBal": "node.js 3.7.2",
      "gateway": {
        "id": "7b8eb0e5-738a-40f5-8515-6b5bf308db9d",
        "bal": "java 3.7.2.25_g2cc0a90-SNAPSHOT",
        "host": "acs-zone-black",
        "pid": 4624,
        "platformId": "black",
        "buildNumber": "3.7.2_25_g2cc0a90-1.x86_64",
        "environmentId": "black"
      },
      "service": {
        "id": "94662691-c1fa-4a5b-9a20-919cb0d5e427",
        "bal": "node.js 3.7.2",
        "host": "acs-zone-black",
        "pid": 5549,
        "platformId": "black",
        "buildNumber": "3.5.3_2_g70b0518-1.x86_64",
        "environmentId": "black"
      }
    },
    "transaction": {
      "id": "53c47c4e-6cc9-41dd-b805-410ebe691d22",
      "origin": "gateway"
    }
  }
}

Error set example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[
  {
    "code": "avid.acs/I0002",
    "details": "Cannot read property 'num1' of undefined",
    "message": "Internal service error",
    "incident": "f284ae42-1b60-48db-b587-fe0971169bad",
    "severity": "ERROR",
    "status": 500,
    "origin": {
      "type": "avid.acs.calculator",
      "realm": "global.test",
      "version": 3
    }
  }
]