[REST] New REST APIs to generate DSL syntax for items and things

[lolodomo]

Related to #4509

Added REST APIs:

• GET /file-format/existing/items to create file format for all existing items in registry
• GET /file-format/existing/item/{itemname} to create file format for an existing item in registry
• GET /file-format/existing/things to create file format for all existing things in registry
• GET /file-format/existing/thing/{thingUID} to create file format for an existing thing in registry
• GET /file-format/existing/thing-from-inbox/{thingUID} to create file format for an existing thing in discovey registry

All these APIs have a boolean parameter named "hideDefaultParameters" to hide or show the configuration parameters having the default value. They are hidden by default.

[lolodomo]

Here is an example of result for things:

Thing astro:moon:e2015c6f37 "Données Astro de Lune" @ "Paris" [geolocation="49.023461463214126,-1.1425781250000002"] {
	Channels:
		Type end : rise#end "Heure Fin" [offset=-1, forceEvent=true]
}
Bridge freeboxos:api:api "Freebox API" [appToken="xxxxx", httpsAvailable=true] {
	Thing active-player player-test "Player Revolution" [remoteCode="123456"]
	Thing player player4k "Player Mini 4k" [id=15]
	Thing revolution serveur-test "Serveur Revolution"
}
Bridge netatmo:account:compte "Netatmo" [clientId="yyyyy", clientSecret="zzzzz"] {
	Bridge weather-station indoor "Indoor" [id="11:22:33:44:55:66"] {
		Thing outdoor exterieur "Sonde extérieure" [id="22:33:44:55:66:77"]
		Thing rain pluviometre "Pluviomètre" [id="33:44:55:66:77:88"]
		Channels:
			Type co2-measurement : max-co2-hour "Max CO2 Last Day" [limit="MAX", period="1day"]
			Type co2-measurement : max-co2-week "Max CO2 Last Week" [limit="MAX"]
			Type co2-measurement : min-co2-hour "Min CO2 Last Day" [period="1day"]
			Type co2-measurement : min-co2-week "Min CO2 Last Week"
			Type noise-measurement : max-noise-hour "Max Noise Last Hour" [limit="MAX", period="1hour"]
			Type noise-measurement : min-noise-hour "Min Noise Last Hour" [period="1hour"]
			Type noise-timestamp : time-max-noise-week "Time Max Noise Last Week" [limit="DATE_MAX"]
			State Number : test-number [param1="Value 1", param2=true, param3=15, 20.5, 25.5, 30]
			Trigger String : test-string [titi=100, toto=true, false, true]
	}
}
Thing ntp:ntp:local "Local Time" [hostname="0.fr.pool.ntp.org", timeZone="Europe/Paris"] {
	Channels:
		Type string-channel : string "Date Heure" [DateTimeFormat="dd-MM-yyyy HH:mm:ss"]
}

[lolodomo]

And the result for items:

Group:Switch:OR (ON, OFF) DemoSwitchGroup [home-group]
Group X "Group X"
Group C "Group C" (X, U)
Group U "Group U" (X)
Color DemoColor (DemoSwitchGroup)
Contact DemoContact
DateTime DemoDateTime
Dimmer DemoDimmer (DemoSwitchGroup) { autoupdate="false" }
Number:Dimensionless DemoHumidity "Humidity [%.0f %%]" <humidity> (U, C) [Humidity, Measurement] { listWidget="" [action="", iconUseState=true], unit="%" }
Number:Dimensionless DemoHumidity2 "Humidity 2" <humidity> (U, C) [Humidity, Measurement] { listWidget="" [action="", iconUseState=true], unit="%" }
Image DemoImage
Location DemoLocation "Demo Location"
Number DemoNumber (U)
Number DemoNumber2 (U) { stateDescription="" [min=-10, max=20, step=0.5, pattern="%.1f"] }
Number DemoNumber3 "Demo Number 3 [%.1f]" (U) { stateDescription="" [min=-10, max=20, step=0.5, pattern="%.1f"] }
Number DemoNumber4 "Demo Number 4" (U) { stateDescription="" [min=-5, max=5, pattern="%.0f", readOnly=true] }
Number DemoNumber5 "Demo Number 5" (U)
Rollershutter DemoRollershutter
String DemoString (X)
String DemoString2 "My String 2 [- %s -]" (X)
String DemoString3 "My String 3 [= %s =]" (X)
String DemoString4 "My String 4 [+++ %s +++]" (X)
String DemoString5 "My String 5" (X)
String DemoString6 "My String 6 []" (X)
String DemoString7 "My String 7" (X)
Switch DemoSwitch "Demo Switch [%s]" <switch> (DemoSwitchGroup) [Control, Light] { matter="OnOffLight" [label="Lampe sur l\'étagère"] }
Number:Temperature DemoTemperature "Setpoint [%.1f °C]" <temperature> (C) [Setpoint, Temperature]
String test { commandDescription="" [options="0=value 0,1,2=Value 2"], stateDescription="" [options="0=Valeur 0,1=Valeur 1,2", pattern="%s"] }
Number test2 "Aujourd\'hui" <none> [Energy, Measurement]
Number:Pressure test_0_1 "Label Test" <if:noto-v1:cityscape-at-dusk> (DemoSwitchGroup, C) [Sensor] { commandDescription=" " [options="0=Valeur 0,1=Valeur 1"], ga="Lock" [inverted=true], unit="bar" }
Number:Pressure test_0_2 "Label , Test = 1" <if:noto-v1:cityscape-at-dusk> (DemoSwitchGroup, C) [Sensor] { commandDescription=" " [options="0=Valeur 0,1=Valeur 1"], ga="Lock" [inverted=true], unit="bar" }
String Donnees_Astro_de_Lune_Evenement_Periode "Événement Période" [Point] { channel="astro:moon:e2015c6f37:rise#event" [profile="system:trigger-event-string"] }
DateTime Donnees_Astro_de_Lune_Heure_Fin "Heure Fin [%1$td/%1$tm/%1$tY %1$tR]" [Point] { channel="astro:moon:e2015c6f37:rise#end" [profile="system:timestamp-offset", offset=30.0], channel="astro:moon:e2015c6f37:rise#start", autoupdate="false" }
DateTime Lune_Heure_Debut "Heure Début [%1$td/%1$tm/%1$tY %1$tR]" [Point] { channel="astro:moon:e2015c6f37:rise#start" }
Color MagicColor { channel="magic:color-light:magicColor:color" }
Dimmer MagicDimmer { channel="magic:dimmable-light:magicDimmer:brightness" }
Switch MagicOnOff { channel="magic:onoff-light:magicOnOff:switch" }

[lolodomo]

@kaikreuzer and @openhab/core-maintainers : for your information, the PR is now ready for review.

[lolodomo]

Go back to draft as I discovered a bug.

[lolodomo]

Problem with items sorting is solved. So ready again.

[lolodomo]

I was certainly too much ambitious when I decided to try also covering #4585 in this PR.
I finally decided to come back to the original perimeter of this PR, that is the needs described in #4509 even if discussion in #4585 oriented the final implementation of this PR in particular with the creation of a new endpoint /file-format..

As a consequence, the PR is smaller and ready for review.

@kaikreuzer : that would be great if you could have a look.

For #4585, another PR will be created based on this one.

[lolodomo]

[lolodomo]

I don't know if I should or not keep the "language" parameter as it is not used by these APIs.

[mherwege]

I don't know if I should or not keep the "language" parameter as it is not used by these APIs.

I agree, not used at this time, so not needed. In the future, when we would support e.g. a YAML format format as well, we can still introduce it with a default value equal to text\vnd.openhab-dsl. Alternative would be to already annotate it with a default so there is no requirement to set it at this time. But it would be an unused parameter for now.

I would be keen to try to create a proper documentation of the generated response, rather than just string if achievable. But that can be a follow-up and doesn't need to be part of this PR.

[lolodomo]

I agree, not used at this time, so not needed. In the future, when we would support e.g. a YAML format format as well, we can still introduce it with a default value equal to text\vnd.openhab-dsl. Alternative would be to already annotate it with a default so there is no requirement to set it at this time. But it would be an unused parameter for now.

Language parameter is to provide a locale, not to select the output format.
For the output format selection I moved as you suggested to a media type combined with the Accept header. Another media type will be added later when a YAML format is added.

I will remove the language parameter.

[lolodomo]

I will remove the language parameter.

I will first check if it makes sense to get a localized version of a thing/item before generating DSL syntax.

[mherwege]

Language parameter is to provide a locale, not to select the output format.

Oops, sorry, of course. I was mixing up things.

[mherwege]

If you are interested, the code to convert to YAML is working in the prototype I created, and could easily be integrated here. See https://github.com/mherwege/openhab-core/tree/yaml

[lolodomo]

If you are interested, the code to convert to YAML is working in the prototype I created, and could easily be integrated here.

This PR introduces nothing related to YAML.
But I will consider you code in next PRs when YAML will be introduced.

[lolodomo]

[openhab-bot]

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/ideas-and-discussion-what-features-do-you-want-in-openhab-5-0/160573/620

[lolodomo]

For information, I changed media types from application/vnd.openhab-dsl into application/vnd.openhab.dsl.item and application/vnd.openhab.dsl.thing.