[RfC] Extend add-ons API (backend & REST)

[ghys]

This initial proposal & RfC is related to #2058 and also to https://github.com/openhab/openhab-addons/issues/8448 to expand the add-ons API to handle multiple sources and versions better.

With these changes I believe we could provide marketplaces as org.openhab.core.addon.AddonService implementations instead of having a separate "marketplace provider" system and REST API as I initially suggested in https://github.com/openhab/openhab-addons/issues/8448. It would also be possible to install alternative versions of add-ons from other sources (for instance an AddonService for https://openhab.jfrog.io/artifactory/libs-snapshot-local/org/openhab/addons/bundles/)

Proposed additions to org.openhab.core.addon.AddonService

• string getId() - returns an ID for the service, for example the KarafAddonService would return "karaf".
• void refreshSource() - refreshes the source used to provide the add-ons, if applicable. getAddons() is supposed to return fast, so there could be caching of info like the Eclipse Marketplace service did, but getting the the most current information could be desirable even if it means waiting a little bit (a loading indicator could be shown in UIs). This method can take longer.
• boolean isDefaultVersion(string addonId, string version) - whether the provided version is the default one according to the service. See below for a typical behavior for .jar add-ons.

Proposed additions to org.openhab.core.addon.Addon

• String contentType - the content-type of the add-on, e.g. application/java-archive for .jar files, so that UI-specific add-on types in YAML or JSON would be recognized with their content type and handled separately by UIs if they support them instead of "installing" them with a /addons/{addonId}/install call
• String configDescriptionURI - the URI of the config description for the installed .jar add-on if it has one (similar to what a binding currently provides but extended to all .jar add-ons with #2058)
• String author - I know this was removed from the binding descriptions in https://github.com/openhab/openhab-core/pull/1844, but the AddonService itself could still offer this information, and the KarafAddonService could return a hard-coded value like "openHAB" or "openHAB contributors"` since official distro add-ons are maintained by the project itself.
• String authorAvatarUrl - URL of an image representing the add-on author (optional)
• String authorUrl - URL of a link representing the add-on author (optional)
• String keywords - see #2058 (comma-separated list)
• String countries - see #2058 (comma-separated list)
• String connection - see #2058
• String detailedDescription - a full HTML description of the add-on, as description should remain in summary form as mentioned in #2058. This field should only be included in a REST response when a particular add-on is requested, and filtered out when the list is requested.
• Set<String, Object> properties - a set of service-specific properties for the addon, for instance individual services could add likesCount, viewsCount, repliesCount, createdDate, lastReplyDate, maturityLevel ... the various author-related fields defined above could also be moved there. Or should services subclass Addon and add their specific properties as fields to the subclasses, in that case would they be available in the REST responses then?

Proposed additions to the /addons REST API (org.openhab.core.io.rest.core.internal.addons.AddonResource)

• GET /addons/services - lists the available add-on services Example response: [{"name": "karaf","default": true},{"name":"jfrog","default":false},{"name":"discourse",default:false}] - the default flag should be attributed to the KarafAddonService, can be hard-coded in the AddonResource
• GET /addons?service={serviceId}&refresh=true - if service is omitted, use "karaf" (this is different than the current behavior where the add-ons from all services would be shown (IMHO the UI should present only the official distro add-ons by default and the others on request only), if refresh is true (false if omitted), call refreshSource() on the service first.
• GET /addons/{addonId}/versions - returns the versions for a particular ID from all services. Example response: [{"version":"3.0.0","service":"karaf","default":true},{"version":"3.1.0-20210104.013516-12","service":"jfrog","default":false},{"version":"3.1.0-20210103.044328-11","service":"jfrog","default":false},...] Like above the default flag should be attributed to the version from the karaf service if present, possibly because the karaf service will always return true for all addons, and the jfrog one will return false. If services share add-on IDs they are expected to play nice with each other. If there are multiple versions including a default one, an UI should 1) present the default version prominently; 2) warn if the user wants to install a non-default version, as there might be API incompatibilities with non-default add-ons sourced from outside the distribution.
• POST /addons/{addonId}/install?service={serviceId}&version={version} installs the specific version of the add-on from the specific provided service. If none of these new query strings as provided, use the one from the KarafAddonService if present (i.e. the one which would have been flagged "default" in the list of versions above) so this is not API breaking
• GET /addons/types?service={serviceId} lists add-on types from the specified service - if service is omitted, use "karaf" (this is different than the current behavior where the add-ons types from all services would be shown. If service="all" merge the results from all services.
• GET /addons/{addonId}/config - returns the configuration for this add-on - depends on #2058 and replaces /bindings/{bindingId}/config for bindings - note that it might be necessary to introduce a "local" add-on service which handles .jar add-ons sideloaded in the addons folder, so the UI gives the user a path to access the configuration for those (see my remark in https://github.com/openhab/openhab-core/issues/2034#issuecomment-753440467
• PUT /addons/{addonId}/config - updates the configuration for this add-on - depends on #2058 and replaces /bindings/{bindingId}/config for bindings

[delid4ve]

I'm somewhat confused on the reasoning for 'custom' jars not showing up in the ui under settings-> bindings.

This was default behaviour in 2.x and is leading to huge confusion (especially newer users).

If they add a custom jar, they kinda know what they are doing and expect to see it installed in the ui, not karaf only which tbh even I only use to change logging levels.

Maybe I'm missing something, but from a 'beginner, end user' perspective it's counter intuitive it not being there.

Maybe if it's a rework of a current included binding it needs to be flagged, I get that as this could cause problems, but for one not in the distro I don't see any harm. They could always just be highlighted red though or something

[J-N-K]

@ghys Except the configDescriptionUri in .jar files: Isn't this all covered by your extensions?

[ghys]

The marketplace PR was inspired by these specs but a lot of the above wasn't implemented (optional call to AddonService.refreshSource, multiple versions management etc.)