ICAR version number in Json

[Harry-UA]

We would like to have the ICAR version number present in the Json files to be able to make version policy agreements with our partners.

[cookeac]

Possible solutions:

1. Have a version endpoint that you can query once each session with a partner (potentially also deliver other version information such as software versions as well)
2. For GET collection, return in the collection (covers all objects)
3. Put in meta of each object

We will think on this and review.

[AndreasSchultzGEA]

we provide a very simple "/version" endpoint which returns a set of key-value pairs of type String:

{
"DairyNet": "44.1.0",
"icar": "1.3.1"
}

This version endpoint is location-independant and is also often used for making first steps to get connected.

[Harry-UA]

This works for all subsequent GET requests to your API so they know what to expect. But what about POST/PUT requests to your API? How do you know what to expect?

[AndreasSchultzGEA]

Maybe I didn't get your point Harry, but why should there be a differentiation between GET and POST/PUT?
If there is more than one version supported, the interfaces have to be clearly separated from each other, e.g. using a different path like

• server:port/v1.3.1/locations....
• server:port/v1.4.2/locations....
  or other comparable means

[Harry-UA]

That could work, but I don't know if it's convenient to have endpoints for all different minor/build versions. To me it sound more logic to have different URL's for (potentially incompatible) major versions and to have a mechanism in place to detect which minor and or build version is used in the communication.

[AndreasSchultzGEA]

I think, we will start to introduce versions in the API when we switch to the next major-version.
All other changes (minor-versions) are expected to be compatible as we stick to semantic versioning.
But as we haven't checked the compatibility in Java (1.3.x to 1.4.y) so far, the grade of compatibility is not known.

[cookeac]

Discussed at the group 27 Nov:

• We felt that Major versions of the specification should be implemented with separate APIs (e.g. V2 in the URL)
• Minor versions should be backwards compatible
• Maybe we could have an API like that originally proposed for Devices which says which events/APIs are supported?
• We couldn't come up with a case where the version of the JSON schema in a resource being POSTed was useful - are there examples?