DDF bundle REST API

This is a collection of thoughts on the REST API for DDF bundle.

See here for bundle format.

This is using classic REST definition; PUT/POST/DELETE on /id

/api/<apikey>/ddf[/<id>]

{
  "config" : {
    "enabled": true,
    "allowlist": null,
    "blocklist": null,
    "source" : "built-in",
    "autoupdate" : false
  },
  "etag": "9bd1fcc627001458ea88c8742e61c692",
  "description":{
    "last_modified":"2023-02-08T23:20z",
    "version":"v1.0.1",
    "min.deconz":"v2.19.3",
    "schema":"devcap1.schema.json",
    "product":"acme 2000",
    "forum":"url-to-forum-entry",
    "ghissue":"url-to-github-entry",
    "vp":[
       ["Philips", "acme 2000"],
       ["Signify", "acme 200"]
    ],
    "other":"stuff"
  }
}

Attributes stored

config.enabled boolean (R/W)

If the DDF should be used by deconz. Used to allow an user to disable a built-in DDF and replace it by a custom one. It's should be defined only when the DDF is stored in the rest API.

{
  "enabled": true
}

config.allowlist and config.blocklist array | null

Used to limit the DDF to a specific list of device, can be in the allowlist and the blocklist. If the list is empty the value is null. A allowlist empty mean that all devices is accepted. A blocklist empty mean that none device is blocked.

{  
  "devices.allowlist": null,
  "devices.blocklist": [
    "device_id_1"
  ],
}

config.source string

Source is used to know from where the DDF is comming from. It's should be defined only when the DDF is stored in the rest API.

Can be a store uri, "built-in" or "user"

Built-in DDF are coming with deconz, they can be disabled but not removed.

{
  "source": "built-in",
  "source": "https://example.com/ikea_tradfri.ddf"
}

config.autoupdate boolean | undefined

To mark the DDF as autoupdating or undefined if the type is not "store". Should we include an auto update function ? For this the gateway need a internet connexion and when we trigger the update ? The update could break/change stuff maybe it's should be manual and let the users which DDF he want update.

description

The device description from the bundle.

Bundle upload / download

This is using classic REST definition; GET/PUT

/api/<apikey>/ddf/<id>/bundle

Download or upload the bundle. If it's a put it's will replace the existing bundle at that location

To add a new bundle the POST request need to be made at /api/<apikey>/ddf/bundle. The request will return the data like it's was made a GET on /api/<apikey>/ddf/<newid>.

Usages

Maybe it's can be done by using the list of loaded DDF and filter the devices but seems heavy to process.

This is using classic REST definition; GET

List the devices that use this DDF. Don't know if it's should be a device list or a "endpoint" list

/api/<apikey>/ddf/<id>/usage

{
  "1": {
    "etag": "026bcfe544ad76c7534e5ca8ed39047c",
    "type": "Extended color light",
    "uniqueid": "00:21:2E:FF:FF:00:73:9F-0A"
  }
}

Stores definitions

This is using classic REST definition; PUT/POST/DELETE on /id

A store is a definition of where the UI can look for DDFS. There will be a main store on the deconz community repo but a user can create his own store.

/api/<apikey>/ddf/stores[/<id>]

{
  "1": {
    "created": "2022-12-26T14:17:12",
    "etag": "9bd1fcc627001458ea88c8742e61c692",
    "name": "Deconz DDF Store",
    "enabled": true,
    "source": "https://github.com/dresden-elektronik/deconz-rest-plugin"
  }
}

UI

The UI will be avaliable as web page but also distributed from the rest api like phoscon.

How to handle multiple gateways store ? Each gateway have his own store collection ? Easier to do, is there that many multi gateways users ?

Features

Text Editor
File upload

DDF Page file

A DDF page need to display all info about it with a Changelog, sample, notes.

For example a page like this : https://vueuse.org/shared/useDateFormat/

Infos to display

Manufacturer name
Product name
Model ID
Badge for status Gold/Silver/...
List of subdevices with a description / sample of attributes

dresden-elektronik / deconz-rest-plugin-v2