API

Route: /summary

Method: GET

Returns an object summarizing all known zones and related metadata.

Response 200 (application/json)

{
  "zones": {
    "default-zone": {
      "clusters": {
        "example": {
          "clusterName": "example",
          "zoneName": "default-zone",
          "name": "Example Service",
          "version": "1.0",
          "owner": "Demo",
          "capability": "Demo",
          "runtime": "GO",
          "documentation": "/services/example/1.0",
          "prometheusJob": "example",
          "minInstances": 1,
          "maxInstances": 1,
          "authorized": true,
          "clusterID": "example",
          "meshID": "default-zone",
          "enableInstanceMetrics": true,
          "enableHistoricalMetrics": true,
          "instances": [
            {
              "name": "dca79626b6a99f6783f490556e4a5062",
              "startTime": 1569247575966
            }
          ],
          "metricsTemplate": "",
          "metricsPort": 8081
        },
        "fibonacci": {
          "clusterName": "fibonacci",
          "zoneName": "default-zone",
          "name": "Fibonacci",
          "version": "1.0.0",
          "owner": "Demo",
          "capability": "Demo",
          "runtime": "GO",
          "documentation": "/services/fibonacci/1.0/",
          "prometheusJob": "fibonacci",
          "minInstances": 1,
          "maxInstances": 1,
          "authorized": true,
          "clusterID": "fibonacci",
          "meshID": "default-zone",
          "enableInstanceMetrics": true,
          "enableHistoricalMetrics": true,
          "instances": [
            {
              "name": "7795eabdbaf06bb83b2947f74e5d0143",
              "startTime": 1570807423191
            }
          ],
          "metricsTemplate": "",
          "metricsPort": 8081
        }
      },
      "metadata": {
        "zoneName": "default-zone",
        "owners": [
          "Demo",
          "Decipher"
        ],
        "capabilities": [
          "Demo",
          "Grey Matter"
        ],
        "clusterCount": 22,
        "clusterStableCount": 17,
        "clusterWarningCount": 3,
        "clusterDownCount": 2,
        "instanceCount": 1
      }
    }
  },
  "metadata": {
    "zoneCount": 1,
    "owners": [
      "Demo",
      "Decipher"
    ],
    "capabilities": [
      "Grey Matter",
      "Demo"
    ],
    "clusterCount": 22,
    "clusterStableCount": 17,
    "clusterWarningCount": 3,
    "clusterDownCount": 2,
    "instanceCount": 30
  },
  "meshes": {
    "default-zone": {
      "clusters": {
        "example": {
          "clusterName": "example",
          "zoneName": "default-zone",
          "name": "Example Service",
          "version": "1.0",
          "owner": "Demo",
          "capability": "Demo",
          "runtime": "GO",
          "documentation": "/services/example/1.0",
          "prometheusJob": "example",
          "minInstances": 1,
          "maxInstances": 1,
          "authorized": true,
          "clusterID": "example",
          "meshID": "default-zone",
          "enableInstanceMetrics": true,
          "enableHistoricalMetrics": true,
          "instances": [
            {
              "name": "dca79626b6a99f6783f490556e4a5062",
              "startTime": 1569247575966
            }
          ],
          "metricsTemplate": "",
          "metricsPort": 8081
        },
        "fibonacci": {
          "clusterName": "fibonacci",
          "zoneName": "default-zone",
          "name": "Fibonacci",
          "version": "1.0.0",
          "owner": "Demo",
          "capability": "Demo",
          "runtime": "GO",
          "documentation": "/services/fibonacci/1.0/",
          "prometheusJob": "fibonacci",
          "minInstances": 1,
          "maxInstances": 1,
          "authorized": true,
          "clusterID": "fibonacci",
          "meshID": "default-zone",
          "enableInstanceMetrics": true,
          "enableHistoricalMetrics": true,
          "instances": [
            {
              "name": "7795eabdbaf06bb83b2947f74e5d0143",
              "startTime": 1570807423191
            }
          ],
          "metricsTemplate": "",
          "metricsPort": 8081
        }
      },
      "metadata": {
        "zoneName": "default-zone",
        "owners": [
          "Demo",
          "Decipher"
        ],
        "capabilities": [
          "Demo",
          "Grey Matter"
        ],
        "clusterCount": 22,
        "clusterStableCount": 17,
        "clusterWarningCount": 3,
        "clusterDownCount": 2,
        "instanceCount": 1
      }
    }
  }
}

Route: /clusters

Method: GET

Returns a list of service clusters, including running instances and start times.

Multiple query parameters may be used:

• status: accepts stable, warning, and down

• clusterName

• zoneName

• name

• version

• owner

• capability

• prometheusJob

• authorized

• enableInstanceMetrics

• enableHistoricalMetrics

ex: GET /clusters?name=Example%20Service&owner=Decipher

Response 200 (application/json)

[
  {
    "clusterName": "example-service",
    "zoneName": "us-east-2",
    "name": "Example Service",
    "version": "1.0",
    "owner": "Decipher",
    "capability": "Example",
    "runtime": "GO",
    "documentation": "/services/example-service/1.0/",
    "prometheusJob": "example-service",
    "minInstances": 1,
    "maxInstances": 1,
    "authorized": true,
    "enableInstanceMetrics": true,
    "enableHistoricalMetrics": false,
    "metricsPort": 8081,
    "instances": [
      {
        "name": "cee8014703400366094f6f2be882579d",
        "startTime": 1548167565788
      }
    ]
  }
]

Method: POST

Adds a new service cluster.

ex: POST /clusters with the following request body:

Request (application/json)

{
  "clusterName": "example-service",
  "zoneName": "us-east-2",
  "name": "Example Service",
  "version": "1.0",
  "owner": "Decipher",
  "capability": "Example",
  "runtime": "GO",
  "documentation": "/services/example-service/1.0/",
  "prometheusJob": "example-service",
  "minInstances": 1,
  "maxInstances": 1,
  "authorized": true,
  "enableInstanceMetrics": true,
  "enableHistoricalMetrics": false,
  "metricsPort": 8081
}

Response 200 (application/json)

{"added": "example-service"}

Route: /clusters/<clusterName>

Method: GET

Returns a list of matching service clusters, including running instances and starttimes.

A query parameter may be used to specify a zoneName.

ex: GET /clusters/example-service?zoneName=us-east-2

Response 200 (application/json)

[
  {
    "clusterName": "example-service",
    "zoneName": "us-east-2",
    "name": "Example Service",
    "version": "1.0",
    "owner": "Decipher",
    "capability": "Example",
    "runtime": "GO",
    "documentation": "/services/example-service/1.0/",
    "prometheusJob": "example-service",
    "minInstances": 1,
    "maxInstances": 1,
    "authorized": true,
    "enableInstanceMetrics": true,
    "enableHistoricalMetrics": false,
    "metricsPort": 8081,
    "instances": [
      {
        "name": "cee8014703400366094f6f2be882579d",
        "startTime": 1548167565788
      }
    ]
  }
]

Method: PUT

Replaces an existing service cluster within a mesh (specified in the request body object).

ex: PUT /clusters/example-service with the following request body:

Request (application/json)

{
  "clusterName": "example-service",
  "zoneName": "us-east-2",
  "name": "My Great Example Service!",
  "version": "1.0",
  "owner": "Decipher",
  "capability": "Exemplar",
  "runtime": "GO",
  "documentation": "/services/example-service/1.0/",
  "prometheusJob": "example-service",
  "minInstances": 1,
  "maxInstances": 2,
  "authorized": true,
  "enableInstanceMetrics": true,
  "enableHistoricalMetrics": false,
  "metricsPort": 8081
}

Response 200 (application/json)

{"replaced": "example-service"}

Method: DELETE

Deletes an existing service cluster within a mesh. Note that a zoneName must be specified via query parameter:

ex: DELETE /clusters/example-service?zoneName=us-east-2

Response 200 (application/json)

{"deleted": "example-service"}

Route: /metrics/<clusterName>/<instance>

Method: GET

ex: /metrics/isprime-cluster-1/96cf8008461085dc439e495d7adabd21

Response 200 (application/json)

{
  "grey-matter-metrics-version": "1.0.0",
  "Total/requests": 0,
  "HTTP/requests": 0,
  "HTTPS/requests": 0,
  "RPC/requests": 0,
  "RPC_TLS/requests": 0,
  "all/requests": 0,
  "all/routes": "",
  "all/latency_ms.avg": 0.000000,
  "all/latency_ms.count": 0,
  "all/latency_ms.max": 0,
  "all/latency_ms.min": 0,
  "all/latency_ms.sum": 0,
  "all/latency_ms.p50": 0,
  "all/latency_ms.p90": 0,
  "all/latency_ms.p95": 0,
  "all/latency_ms.p99": 0,
  "all/latency_ms.p9990": 0,
  "all/latency_ms.p9999": 0,
  "all/errors.count": 0,
  "all/in_throughput": 0,
  "all/out_throughput": 0,
  "go_metrics/runtime/num_goroutines": 14,
  "system/start_time": 1548167566942,
  "system/cpu.pct": 2.275601,
  "system/cpu_cores": 8,
  "os": "linux",
  "os_arch": "amd64",
  "system/memory/available": 17711955968,
  "system/memory/used": 8031883264,
  "system/memory/used_percent": 31.845620,
  "process/memory/used": 72808696
}

Route: /zones

Method: GET

Returns a list of metadata objects related to each known mesh.

Response 200 (application/json)

[
  {
    "zoneName": "us-east-1",
    "owners": [
      "Decipher",
      "Grey Matter"
    ],
    "capabilities": [
      "metrics",
      "observability"
    ],
    "serviceCount": 6,
    "stableServiceCount": 4,
    "warningServiceCount": 1,
    "downServiceCount": 1,
    "instanceCount": 5
  },
  {
    "zoneName": "us-east-2",
    "owners": [
      "OpenShift",
      "Solutions"
    ],
    "capabilities": [
      "containers",
      "environments"
    ],
    "serviceCount": 4,
    "stableServiceCount": 3,
    "warningServiceCount": 1,
    "downServiceCount": 0,
    "instanceCount": 4
  }
]

Method: POST

Adds a new mesh (i.e. registers a new gm-xds instance with Catalog).

Request (application/json)

{
  "serverAddress": "discovery.myhost.com:50000",
  "zoneName": "north-region"
}

Response 200 (application/json)

{"added": "north-region"}

Route: /zones/<zoneName>

Method: GET

Returns a metadata object for a specified mesh.

A query parameter may be used to specify a zoneName.

ex: GET /zones/us-east-2

Response 200 (application/json)

{
  "zoneName": "us-east-2",
  "owners": [
    "OpenShift",
    "Solutions"
  ],
  "capabilities": [
    "containers",
    "environments"
  ],
  "serviceCount": 4,
  "stableServiceCount": 3,
  "warningServiceCount": 1,
  "downServiceCount": 0,
  "instanceCount": 4
}

Method: DELETE

Deletes an existing mesh AND its service clusters from the Catalog.

ex: DELETE /zones/north-region

Response 200 (application/json)

{"deleted": "north-region"}

Route: /services (Deprecated)

Method: GET

The response contains the entire listing of services that should be present in the mesh, as well as running instances and starttimes.

Response 200 (application/json)

[
  {
    "clusterName": "gm-catalog",
    "zoneName": "us-east",
    "name": "Grey Matter Catalog",
    "version": "1.0",
    "owner": "Decipher",
    "capability": "gm-catalog",
    "runtime": "GO",
    "documentation": "/services/catalog/1.0/",
    "prometheusJob": "catalog-1.0",
    "minInstances": 1,
    "maxInstances": 1,
    "authorized": true,
    "enableInstanceMetrics": true,
    "enableHistoricalMetrics": false,
    "metricsPort": 8081,
    "instances": [
      {
        "name": "ebda09996c7f1f7ff2f83dfcdec5b02f",
        "startTime": 1553863334185
      }
    ]
  },
  {
    "clusterName": "example-service",
    "zoneName": "us-west",
    "name": "Example Service",
    "version": "1.0",
    "owner": "Decipher",
    "capability": "Example",
    "runtime": "GO",
    "documentation": "/services/example-service/1.0/",
    "prometheusJob": "example-service-1.0",
    "minInstances": 1,
    "maxInstances": 1,
    "authorized": true,
    "enableInstanceMetrics": true,
    "enableHistoricalMetrics": false,
    "metricsPort": 8081,
    "instances": [
      {
        "name": "1d82794e5381fb8fc568195806c3a1b3",
        "startTime": 1553863266131
      }
    ]
  }
]

Route: /metrics/<service name>/<version>/<instance> (Deprecated)

Method: GET

ex: /metrics/isPrime%20Service/1.0/96cf8008461085dc439e495d7adabd21

Response 200 (application/json)

{
  "grey-matter-metrics-version": "1.0.0",
  "Total/requests": 0,
  "HTTP/requests": 0,
  "HTTPS/requests": 0,
  "RPC/requests": 0,
  "RPC_TLS/requests": 0,
  "all/requests": 0,
  "all/routes": "",
  "all/latency_ms.avg": 0.000000,
  "all/latency_ms.count": 0,
  "all/latency_ms.max": 0,
  "all/latency_ms.min": 0,
  "all/latency_ms.sum": 0,
  "all/latency_ms.p50": 0,
  "all/latency_ms.p90": 0,
  "all/latency_ms.p95": 0,
  "all/latency_ms.p99": 0,
  "all/latency_ms.p9990": 0,
  "all/latency_ms.p9999": 0,
  "all/errors.count": 0,
  "all/in_throughput": 0,
  "all/out_throughput": 0,
  "go_metrics/runtime/num_goroutines": 14,
  "system/start_time": 1548167566942,
  "system/cpu.pct": 2.275601,
  "system/cpu_cores": 8,
  "os": "linux",
  "os_arch": "amd64",
  "system/memory/available": 17711955968,
  "system/memory/used": 8031883264,
  "system/memory/used_percent": 31.845620,
  "process/memory/used": 72808696
}