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

[ChadJessup]

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.

[ericsampson]

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

Out of curiosity for general JSON HTTP API design, what do you prefer instead? I've come up against lots of different opinions on this topic between multiple teams, with pros and cons either way.

[ChadJessup]

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

Out of curiosity for general JSON HTTP API design, what do you prefer instead? I've come up against lots of different opinions on this topic between multiple teams, with pros and cons either way.

If using OpenApi (Swagger) there is an enum descriptor: https://swagger.io/docs/specification/data-models/enums/
Before OpenApi there were extensions to the Swagger format that would do the same. I believe they were from Microsoft originally.

If not using something like OpenApi, I think just a string denoting the value works well: "serviceType": "Executable"
This has another benefit of decoupling language features from the API a bit. I believe that not all languages have enums that map to numbers, as an example.

It's also more along the lines of a self describing API, at least for the values that have been returned to the caller. I can get a payload with "serviceType": "Container", and "serviceType": "Executable" and know a lot more automatically than "serviceType": 1 and "serviceType": 2.

In extremely perf sensitive APIs the overhead to another string might concern some folks, but those APIs probably shouldn't be using json. :)

@ericsampson - I'm curious what you've heard for being pros to ints here? I'm sure there are some!

[rynowak]

This is awesome feedback, thank you!

We haven't a polish pass on the API yet - and I think we're a few steps away from that. We'll use this when we do.

I'm curious what you've heard for being pros to ints here? I'm sure there are some!

I learned a lot about this from talking with @steveharter and @JamesNK when we built System.Text.Json last year. One of the reasons why .NET serializers default to int is that you really have to intend for the enum to be serializable as a string for that to work. Enum features like flags or unnamed values would have to throw an exception if you're using strings.

In terms of defining a good API, I definitely prefer strings. JSON is supposed to be human readable/writable.

[rynowak]

If someone wants to take this on we're open to any and all of these suggestions. We think these are good ideas, but we're not working on it right now because nothing consumes the api.... yet 😉