Suggestions for tye api json to be more friendly to other systems and to the march of time.

What should we add or change to make your life better?

Inspecting http://localhost:8000/api/v1/services after doing the first couple tutorials, shows that the tye services api is returning json objects in some cases, where arrays might make more sense, or vice-versa. I figured it'd be best to bring this up early, as any change would be a breaking change.

--

I haven't explored every feature yet, but [0].replicas will be a problem for some languages and auto generation of objects from json, and if it could be an array, that'd be super-duper-rad.

replicas": {
"backend_d42b8943-2": {

--

While it's no longer really a security concern like it used to be (older browsers): https://haacked.com/archive/2009/06/25/json-hijacking.aspx/

The json payload is returned as a top-level array, which means backwards compatible changes to the overall structure won't be possible...

[
  {
    description: {},
    restarts: 0,
    serviceType: 1,
    status: {},
    replicas: {}
  },
  {
    description: {},
    restarts: 0,
    serviceType: 1,
    status: {},
    replicas: {}
  }
]

If wrapped in a containing json object, a low-likelihood security issue is mitigated, auto-generation of code is easier, backwards compatible changes can be applied (new properties, arrays, objects), the payload can be enriched/combined with by other systems, and indexing in something like ElasticSearch tends to go more smoothly:

{
"services":  [
    {
      description: {},
      restarts: 0,
      serviceType: 1,
      status: {},
      replicas: {}
    },
    {
      description: {},
      restarts: 0,
      serviceType: 1,
      status: {},
      replicas: {}
    }
  ],
  "backwardsCompatibleChange": true,
}

--

Minor suggestion: Enums being an int (serviceType: 1) are very difficult to troubleshoot, and integrate against.

Why is this important to you?

I write a lot of glue services, infrastructure services, pipelines, automation, APIs - and deal a lot with 3rd party json apis, especially in regards to internalish ones like /api/v1/services. Minor tweaks like the above suggestions go very far on ecosystems that will rely on something like Tye. Especially, when people start to contort it in ways that were never expected.

Custom build systems, monitoring, CI/CD pipelines, etc will be hooked up to this almost immediately, and I found the above suggestions really help make a product 'snap' into place for Infra/Ops/SRE-type teams.

I'd be happy to get a PR in with these suggestions, but I wanted to gauge interest first.