Using OpenSearch Cat API Response Formats

I’ve been working on the new OpenSearch OpenAPI Specification that aims to properly document OpenSearch RESTful APIs. The spec is to be used to auto-generate OpenSearch clients in Python, Java, .NET, etc. One of the neat features of the API specification repo is a set of declarative YAML integration tests that ensure that the spec has the correct request parameters, and that it matches the actual responses from the server. This is particularly useful when documenting a large existing API such as OpenSearch with its 1021 known APIs.

Thus, I recently added support for text/plain, application/yaml, application/cbor, and application/smile response types to the test tooling.

I’ve heard of YAML, but what is SMILE or CBOR?!

OpenSearch _cat API stands for “Compact and Aligned Text”.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat
=^.^=
/_cat/allocation
...

Do you see the =^.^= cat? Neat! This was a content-type: text/plain; charset=UTF-8 response.

Other CAT APIs respond with text the same way.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/indices

green  open .plugins-ml-model-group      LDXIur-YTqim9fiEHLJZ1w 1 0    0 0  10.3kb  10.3kb
yellow open security-auditlog-2024.05.30 7yBZpI7HS22-6mZtPrVg2g 1 1   62 0  78.8kb  78.8kb

You can ask for JSON, application/json. Pipe it with jq.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/indices?format=json | jq

[
  {
    "health": "green",
    "status": "open",
    "index": ".plugins-ml-model-group",
    "uuid": "LDXIur-YTqim9fiEHLJZ1w",
    "pri": "1",
    "rep": "0",
    "docs.count": "0",
    "docs.deleted": "0",
    "store.size": "10.3kb",
    "pri.store.size": "10.3kb"
  },
  {
    "health": "yellow",
    "status": "open",
    "index": "security-auditlog-2024.05.30",
    "uuid": "7yBZpI7HS22-6mZtPrVg2g",
    "pri": "1",
    "rep": "1",
    "docs.count": "62",
    "docs.deleted": "0",
    "store.size": "78.8kb",
    "pri.store.size": "78.8kb"
  }
]

You can ask for YAML, application/yaml.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/indices?format=yaml

yaml
---
- health: "green"
  status: "open"
  index: ".plugins-ml-model-group"
  uuid: "LDXIur-YTqim9fiEHLJZ1w"
  pri: "1"
  rep: "0"
  docs.count: "0"
  docs.deleted: "0"
  store.size: "10.3kb"
  pri.store.size: "10.3kb"
- health: "yellow"
  status: "open"
  index: "security-auditlog-2024.05.30"
  uuid: "7yBZpI7HS22-6mZtPrVg2g"
  pri: "1"
  rep: "1"
  docs.count: "62"
  docs.deleted: "0"
  store.size: "78.8kb"
  pri.store.size: "78.8kb"

Or for CBOR, which stands for “Concise Binary Object Representation”. Pipe it using cbor2.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/indices?format=cbor

[{"health": "green", "status": "open", "index": ".plugins-ml-model-group", "uuid": "LDXIur-YTqim9fiEHLJZ1w", "pri": "1", "rep": "0", "docs.count": "0", "docs.deleted": "0", "store.size": "10.3kb", "pri.store.size": "10.3kb"}, {"health": "yellow", "status": "open", "index": "security-auditlog-2024.05.30", "uuid": "7yBZpI7HS22-6mZtPrVg2g", "pri": "1", "rep": "1", "docs.count": "62", "docs.deleted": "0", "store.size": "78.8kb", "pri.store.size": "78.8kb"}]

Finally, SMILE is another binary data format that defines a binary equivalent of standard JSON data format.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/indices?format=smile

:)
???healthDgreen?statusCopen?indexV.plugins
...

Yes, the data is prefixed with :). Use smile-tool to decode the data.

$ curl -k -u admin:$OPENSEARCH_PASSWORD https://localhost:9200/_cat/indices?format=smile | smile-tool -d

[{"health": "green", "status": "open", "index": ".plugins-ml-model-group", "uuid": "LDXIur-YTqim9fiEHLJZ1w", "pri": "1", "rep": "0", "docs.count": "0", "docs.deleted": "0", "store.size": "10.3kb", "pri.store.size": "10.3kb"}, {"health": "yellow", "status": "open", "index": "security-auditlog-2024.05.30", "uuid": "7yBZpI7HS22-6mZtPrVg2g", "pri": "1", "rep": "1", "docs.count": "62", "docs.deleted": "0", "store.size": "78.8kb", "pri.store.size": "78.8kb"}]

Daniel Doubrovkine

Using OpenSearch Cat API Response Formats opensearch

Using OpenSearch Cat API Response Formats