Ambiguous documentation for REST discovery

[bkp7]

The discovery.json schema and supporting documentation are ambiguous as regards the following questions:

Q: is the format of group of endpoints eg. "v1" fixed or is it freetext? Q: is the path to the service fixed .../signalk/v1/api/ ie. are api and stream mandated and is the use of the v1 in a fixed format? Q: how does a server present both IPv4 and IPv6 interfaces? Or perhaps we only support IPv4?

In light of the above is the following allowed/expected? (it does validate against the schema). If not how should these services be advertised?

{
  "endpoints": {
    "v1-alpha": {
      "version": "1.1.0-alpha1",
      "signalk-http": "http://192.168.1.5/signalk/alpha/rest/",
      "signalk-http": "http://[21DA:D3:0:2F3B:2AA:FF:FE28:9C5A]/signalk/alpha/rest/",
      ...
    },
    "v1": {
      "version": "1.0.4",
      "signalk-http": "http://192.168.1.5/signalk/stable/rest/",
      ...
    }
  }
}

[bkp7]

Also need to consider ease of use / wisdom of duplicated keys, which may not be supported in some JSON implementations, even though they are valid JSON.

[tkurki]

Endpoint group format has not been fixed, mostly because it is meant for future versions support. The idea is that there will probably probably be a new version on the future and we need a way to support multiple versions. I assume most if not all client software just use v1.

A really good point about IPv6. Too bad we did not consider even multiple nics. Would it work so that a server may advertise multiple addresses, v4 and v6, and discovery via v6 gives you v6 endpoints?

I don’t think there is anything the current spec that says v4 only, just that discovery for both does not work with one discovery document.

stream and api are fixed - there is no way to bootstrap your way to them.

[bkp7]

I have modified the docs to clarify the above.

[tkurki]

stream and api are fixed - there is no way to bootstrap your way to them.

This is very embarrassing and I apologize for my mistake, I don't know what kind of mushrooms I was on where I wrote this - if we specify the full url in the discovery document why would a client not be able to bootstrap its way to the endpoints?

This is a bit problematic as the spec uses full urls all over the place and I think many clients do not do discovery but just point themselves at hardcoded paths, only allowing host & port parameters.