salt-api cherrypy Response as Array

[Linuturk]

Description of Issue

When you query salt-api for groups of items such as jobs or minions, the api returns a JSON response that's formatted as a single object instead of an Array or List of those items.

Setup

Configure salt-api according to the cherrypy documentation and query the /jobs/ or /minions/ endpoints.

Steps to Reproduce Issue

Once you query these endpoints, you'll see a response similar to these:

Notice the Jobs endpoint returns a document with key "return" that contains an array. This array doesn't contain an object per job, but instead returns a single massive object with all the jobs as top level keys in that single object. This means we can't marshal this JSON to a data structure that would allow discovery of the jobs in the response. You have to know the job id to know which key to grab from the single, large document.

{
  "return": [
    {
      "20190805225029325647": {
        "Function": "saltutil.find_job",
        "Target": [
          "minion1",
          "minion2",
          "minion3"
        ],
        "Target-type": "list",
        "User": "saltapi",
        "StartTime": "2019, Aug 05 22:50:29.325647",
        "Arguments": [
          "20190805225024236030"
        ]
      },
      "20190805225024236030": {
        "Function": "grains.items",
        "Target": "*",
        "Target-type": "glob",
        "User": "saltapi",
        "StartTime": "2019, Aug 05 22:50:24.236030",
        "Arguments": []
      }
    }
  ]
}

A better jobs response would look like the following. We can now iterate through the array of objects, and identify the job based on the jid key. This also allows us to count the total number of jobs.

{
    "return": [
        {
            "jid": "20190805225029325647",
            "Function": "saltutil.find_job",
            "Target": [
                "minion1",
                "minion2",
                "minion3"
            ],
            "Target-type": "list",
            "User": "saltapi",
            "StartTime": "2019, Aug 05 22:50:29.325647",
            "Arguments": [
                "20190805225024236030"
            ]
        },
        {
            "jid": "20190805225024236030",
            "Function": "grains.items",
            "Target": "*",
            "Target-type": "glob",
            "User": "saltapi",
            "StartTime": "2019, Aug 05 22:50:24.236030",
            "Arguments": []
        }
    ]
}

Here's a similar example using the /minions/ endpoint.

{
  "return": [
    {
      "minion1": false,
      "minion2": false,
      "minion3": false
    }
  ]
}

And a more ergonomic response:

{
    "return": [
        {
            "minionId": "minion1",
            ... additional minion data ...
        },
        {
            "minionId": "minion2"
        },
        {
            "minionId": "minion3"
        }
    ]
}

Versions Report

# salt --versions-report
Salt Version:
           Salt: 2019.2.0
 
Dependency Versions:
           cffi: 1.5.2
       cherrypy: 3.5.0
       dateutil: 2.4.2
      docker-py: Not Installed
          gitdb: 0.6.4
      gitpython: 1.0.1
          ioflo: Not Installed
         Jinja2: 2.8
        libgit2: 0.24.0
        libnacl: Not Installed
       M2Crypto: Not Installed
           Mako: 1.0.3
   msgpack-pure: Not Installed
 msgpack-python: 0.4.6
   mysql-python: Not Installed
      pycparser: 2.14
       pycrypto: 2.6.1
   pycryptodome: Not Installed
         pygit2: 0.24.0
         Python: 2.7.12 (default, Nov 12 2018, 14:36:49)
   python-gnupg: 0.3.8
         PyYAML: 3.11
          PyZMQ: 15.2.0
           RAET: Not Installed
          smmap: 0.9.0
        timelib: Not Installed
        Tornado: 4.2.1
            ZMQ: 4.1.4
 
System Versions:
           dist: Ubuntu 16.04 xenial
         locale: UTF-8
        machine: x86_64
        release: 4.4.0-1087-aws
         system: Linux
        version: Ubuntu 16.04 xenial

[Linuturk]

An example of this pattern can be found at https://jsonapi.org/format/#fetching-resources-responses specifies

"A server MUST respond to a successful request to fetch a resource collection with an array of resource objects or an empty array ([]) as the response document’s primary data."

The format of the response could be changed and maintain backwards compatibility by versioning the new version. A prefix of v2/ to the jobs and minions routes would work.

[twangboy]

This might be best done with a new outputter to avoid breaking existing interfaces.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

If this issue is closed prematurely, please leave a comment and we will gladly reopen the issue.

[stale[bot]]

Thank you for updating this issue. It is no longer marked as stale.