Service Declaration

All micro-services declarations for the Avid Platform are provided in JSON format. Here is example of the service contract

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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "serviceType": "avid.acs.calculator",
  "serviceRealm": "global.test",
  "serviceVersion": 3,
  "description": "Performs simple arithmetic.",
  "compatibleVersions": [2, 1],
  "scope": "multi-zone",
  "errorCodes": {
    "DIVIDE_BY_ZERO": {
      "status": 500,
      "severity": "ERROR",
      "messageTemplate": "Division by zero, %{num1} and %{num2}",
      "origin": "SERVICE"
    },
    "ops": {
      "add": {
        "description": "Returns the sum of two numbers.",
        "examples": {
          "add": {
            "num1": 5,
            "num2": 3
          }
        },
        "rest": {
          "path": "calculator/add",
          "method": "GET",
          "queryParams": [
            "num1",
            "num2"
          ]
        }
      },
      "divide": {
        "description": "Returns the quotient of two numbers.",
        "examples": {
          "normal divide": {
            "num1": 12,
            "num2": 3
          },
          "division by zero": {
            "num1": 12,
            "num2": 0
          }
        },
        "rest": {
          "path": "calculator/divide",
          "method": "GET",
          "queryParams": [
            "num1",
            "num2"
          ]
        }
      }
    }
  }
}

Service Contract Anatomy

Root JSON object of the service contract has the following fields:

Field Name Type Description Is Required Default
serviceType string unique name given to each service true n/a
serviceRealm string realm, where this service is available false “global”
serviceVersion integer version of the service true n/a
description string detailed description of the service false empty string
compatibleVersions array array of integers, providing list of service versions which are compatible with current version false n/a
scope string one of two values “zone” or “multi-zone”, declare if service must be accessible from zone where it is running only or from any zone false “zone”
ops object list of service operations false {}
errorCodes object list of errors, which service may return false {}

Service Operations

Service operations object contains unique fields. Field names are representing names of service operations provided by given service. In the following example, two operations are provided in the “ops” object: “add” and “divide”.

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
36
37
38
39
40
{
  "add": {
    "description": "Returns the sum of two numbers.",
    "examples": {
      "add": {
        "num1": 5,
        "num2": 3
      }
    },
    "rest": {
      "path": "calculator/add",
      "method": "GET",
      "queryParams": [
        "num1",
        "num2"
      ]
    }
  },
  "divide": {
    "description": "Returns the quotient of two numbers.",
    "examples": {
      "normal divide": {
        "num1": 12,
        "num2": 3
      },
      "division by zero": {
        "num1": 12,
        "num2": 0
      }
    },
    "rest": {
      "path": "calculator/divide",
      "method": "GET",
      "queryParams": [
        "num1",
        "num2"
      ]
    }
  }
}

Examples

Each operation object has the following fields:

Field Name Type Description Is Required Default
description string description of the service operation false empty string
examples object list of usage examples for the given operation false {}
rest object REST endpoint definition for the given operation, if operation must be exposed for HTTP access via Avid Upstream false {}

Examples object is providing list of usage examples for the given operation. Field names of the examples object are representing example names. Value of each example object is sample message corresponding to example. In the following code block we have two examples of service operation usage. One named “normal divide” another named “division by zero”. For message parameters, both examples are taking object with two fields “num1” and “num2” with different values.

1
2
3
4
5
6
7
8
9
10
{
  "normal divide": {
    "num1": 12,
    "num2": 3
  },
  "division by zero": {
    "num1": 12,
    "num2": 0
  }
}

REST Endpoint

If service must expose access to service operation(s) via HTTP REST, to be accessible through the Avid Upstream, it must provide REST declaration for such operation(s). Rest object has the following fields:

Field Name Type Description Is Required Default
path string HTTP path to the service operation true n/a
method string HTTP method to be invoked (GET, POST, DELETE etc) false GET
queryParams array array of query parameters false []

Path may contain dynamic parts, parameter name in the curly brackets, like “instances/{instanceId}/health”. In this case value of instanceId will be extracted from the path and passed in the message.

Error Codes

If service going to return errors back to sender under some circumstances, it must register these errors in the “errorCodes” object. Field names of the “errorCodes” object are representing error codes registered with the service. Each error code is the object, with the following fields:

Field Name Type Description Is Required Default
description string description of the error false empty string
status integer valid HTTP status that can be used by Avid Upstream true
severity string a syslog style log level: EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG true
messageTemplate string error message template in en_US locale that may include %{} placeholders for error message parameters/arguments expansion. This template and parameters should contain only sanitized information that any end user may see without leaking information. However the messageTemplate and parameters should carry meaningful information true