This page last changed on May 24, 2012 by ebariaux.

As we're moving into the next big version of the controller, changes to the REST API will be required.
I started this thread to discuss those.

As we move forward, one point we'd like to take into consideration is backward compatibility.
To address this, a controller might want to support multiple versions of the API and clients (e.g. consoles) can also support multiple versions of the API.

We add a REST call for the controller to report its API version(s) and other capabilities. Clients will use it as a first call to know what API level to use for communication.
If the controller does not support this call, the client must consider it adheres to API v2.0

Request Controller Capabilities

  • Request URL:
    /rest/capabilities
  • Request Method: GET
  • Parameters: none
  • Example Request URL:
    http://localhost:8080/controller/rest/capabilities

Example Response

  • content-type: application/xml
 
<?xml version="1.0" encoding="UTF-8"?>
<openremote xmlns="http://www.openremote.org" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xmlns:schemaLocation="http://www.openremote.org/capabilities.xsd">
  <rest-api-versions>
    <version>2.2</version>
    <version>2.1</version>
  </rest-api-versions>

  <security>
    <api path="panels" security="none" ssl-enabled="false"/>
    <api path="panel" security="HTTP-basic" ssl-enabled="true"/>
    ...
  </security>

  <capabilities>
    <capability name="SIP">
      <property name="port" value="5060"/>
    </capability>
  </capabilities>
</openremote>

<rest-api-versions>
will return an ordered list of supported version (descending version order). The console will pickup the highest version it supports for further communication with the controller.

<security>
indicates the security that is enforced at application server level on each REST call. An <api> entry for each API call indicates the security level (for now only none or HTTP-basic are supported). It also indicates if SSL can be used to call that API.

<capabilities>
lists all the additional capabilities that this controller supports. For instance, the sip entry indicates that the controller supports SIP natively and console with VoIP support can register to this controller. The <property> entries under <capability> allow some capability specific information to be communicated without requiring any change to the XML structure.

Question : do we need a specific version of the XMLs returned (e.g. to panel) or is this described as part of the REST API version ?

Errors

  • No specific error, 2.0 controllers will return a 404 error code for this call

Current (2.0) APIs use a URL prefix of /rest. To support multiple versions, going forward, the prefix will be /rest/<API version> e.g. /rest/2.1 (The exception being the capabilities call above, as the version is unknown at this stage)

Some consideration needs to be paid to the JSON/JSONP REST API support, the current JSON-lib library does a rather bad job of serialising the XML into JSON and I have had to create a JSONFormatter to do some post processing of the JSON before returning it to the client, far from ideal. Haven't looked into options much but other JSON libraries can accept XSLT style sheets which tell it exactly how to serialise the XML into JSON so values are in the correct format etc.

Posted by kurrazyman at Nov 13, 2011 11:09

A security info REST API call would be very useful (/rest/0.0/security). At present I just perform a fictitious panel enquiry (rest/panel/a) and check the Response code if it is 403 then the panel is secure but as each part of the REST API can be secured independently this isn't ideal. The security info should tell us: -

*REST Commands and security state of each - Secure un-secure
*Security Type (HTTP Basic, HTTP Digest, Form Based, HTTPS Client) - can we assume same security constraints used for all REST Command URLs
*SSL Enabled

Posted by kurrazyman at Nov 13, 2011 11:30

Almost like we need a top level REST API call for controller info (/rest/0.0/controllerinfo) that could incorporate the API version and security info

Posted by kurrazyman at Nov 13, 2011 11:32

There is also a need for obtaining more panel information from the REST API, see below discussion with Juha: -

One thing for the future, it would be useful if panel dimensions were available through the REST API (I don't even think this info is in the panel.xml) but the reason it would be useful is that on desktops I could size the console unit emulator to match the dimensions of the selected panel, at present I'd have to iterate through the screen elements and determine the limits from the widget positions, this is just a nicety and could possibly allow for a setting in the console to only show panels with a compatible size.

Agreed, and has been on my list of changes for panel.xml – the resolution should be explicitly declared there, along with other potential properties, such as if one particular design is only intended for specific iOS device(s) then we can only present those designs as a choice to the user (further options may include things like forcing the console to skip panel choice altogether and/or lock the console to a single design which is driven by the controller-side configuration – this will come up fairly quickly on commercial/public installations).

Posted by kurrazyman at Nov 13, 2011 11:39

The REST API in the current controller is a bit of a mess and is probably on the list of things to be re-done. A JSON error response code is required for "JSON failure to parse xml" at present there is no mechanism for this event.

Posted by kurrazyman at Nov 18, 2011 18:41

Could do with an ID associated with each Tab Bar to make it easier to identify tab bar changes between groups.

Posted by kurrazyman at Nov 19, 2011 21:58

Why do you need to know this before hand ? I mean why a fictitiuous panel enquiry? Why not just make the real call and if you receive an authentication request pop-up a panel for the user to fill-in credentials?

Posted by ebariaux at Nov 28, 2011 08:42

Isn't that the /capabilities API I was proposing above ? (except you want to add security info). Or is this something different ?

Posted by ebariaux at Nov 28, 2011 08:43

Yes it is the same thing with the addition of the security info

Posted by kurrazyman at Nov 28, 2011 16:46

Need to know this at the controller list/settings stage at which point the panel names would not be known, so rather than get a list of panels and then query the first one in the list it is quicker to just make up a panel name and test that....works OK as a kludge.

Posted by kurrazyman at Nov 28, 2011 16:48

Hi,

I realize I'm both a nube and a johnny-come-lately here, but I'd like to make a suggestion.

The <sip/> tag describes a capability of the controller. I would suggest that this should be wrapped in something like a <capabilities> or <supports> tag. Inside that guy could be a list of things this controller supports. This could also be slightly expanded to allow the controller to indicate versions of the technology supported (if that's relevant for that capability).

An example:
<supported-capabilities>
<protocol>sip</protocol>
<protocol version="3.0">magic</protocol>
</supported-capabilities>

This would allow future growth without having to hack the structure of this xml.

. Topher

Posted by topher_zicornell at Dec 12, 2011 02:43

Looks very good. Go ahead with this.

  • By my reading we remain backward/forward compatible since this is an additional REST call, and does not require changes to existing API
  • On Richard's point of panel dimensions, that should be a separate additional REST API call for specific panel identity (specified the same way as Eric did here for controller's capabilities). Same could be done for flagging certain panels for specific console/panel devices.
  • I agree on Topher's point of capabilities should allow structured data – however capabilities are not merely protocols so the structure should remain arbitrary (and string content should be allowed as well, as shown in the original example). At that point this should be just a concern on defining the schema for this document to allow that (if we want to lock down a schema) but the 'hacking' part cannot be avoided with an arbitrary structure.

Question : do we need a specific version of the XMLs returned (e.g. to panel) or is this described as part of the REST API version ?

Not sure I understood the question – do you mean if we should version the other XML return documents explicitly as well?

Posted by juha at Apr 16, 2012 21:40

On Richard's point of panel dimensions, that should be a separate additional REST API call for specific panel identity (specified the same way as Eric did here for controller's capabilities). Same could be done for flagging certain panels for specific console/panel devices.

Actually on this, I'd suspect additional optional elements for these features could be added to the 2.1 version of XML return document to /rest/2.1/panels request – since it will be an explicit path to 2.1 version it won't impact existing installations but can be taken advantage of by 2.1 capable panels once this current REST API controller capability info has been implemented. Screen dimensions and panel hardware/OS type should at least be relevant.

Posted by juha at Apr 16, 2012 21:45

Eric, while you're prototyping this on panels, would like to request this feature:

  <capability>DISABLE_PANEL_SELECTION</capability>

For the controller to instruct the panel that it won't allow the user to select panel design but will deliver a preconfigured panel, and therefore the panel should skip the selection altogether. Subsequent calls to /rest/2.1/panels should return just a single panel ID per hardware/OS type (if this is included, see above) or alternatively just a single generic panel ID that has no hardware/OS types defined which is also used as a default panel ID if a hardware/OS match was not found. The panel would then automatically request the panel definitions using the matching panel ID.

This skips a step for the panel user in configuration where they're never intended to choose anything but one design, and are never intended to change to a different panel design (think many commercial settings).

Posted by juha at Apr 16, 2012 21:58

Regarding the question, what I meant is we will have a version of the REST API supported by the controller, so that will define the calls that are recognized along with the XML/JSON document and error code that each call generates.
But do we also want to have a specific version for the panel.xml and controller.xml files, that is files exported from the modeler ? And do we want those to be able to evolve independently?
I guess yes, as those files are a contract between the designer and the controller and do not directly impact the consoles.
The XML returned to the console (e.g. from a call to /rest/panel/<panel id>, which is different from the main panel.xml file), is defined by the REST API version. So controller API 2.1, defines that there is a /rest/panel/<panel id> call and what the XML returned by that call is.

Posted by ebariaux at Apr 17, 2012 10:13

Agreed on the feature but I don't see that as a capability that the controller should advertise.
The way I would do it is:

  • have these concepts defined in the designer and be part of the panel.xml generated by the designer
  • the ORB can interpret this and react accordingly to generate the appropriate response to the console

So for this specific case:

In the modeler, have a generic UI configuration that defines:

  • the default panel (irrelevant of the hardware/os)
  • if the user is allowed to select a panel or not

In the panel.xml, we would have something like

<ui_config defaultPanelId="1" panelUserSelectable="false"/>

The controller interprets this and when it receives a /rest/panels call, will only return 1 entry in the list like

<?xml version="1.0" encoding="UTF-8"?>
<openremote xmlns="http://www.openremote.org" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            xmlns:schemaLocation="http://www.openremote.org/panel.xsd">
  <panels userSelectable="false">
    <panel id="1" name="Dad's iPhone"/> <!-- 'name' is logical identity -->
  </panels>
</openremote>

This is still a temporary solution, because I believe we should be able to:

  • have different users with different privileges (so some users can choose a panel, others not)
  • have a way to password protect access to the settings screen altogether (so that in commercial install, a user can not go to a different controller or change anything else)

I'll start some other thread to discuss the changes required on the panel configuration level.

Posted by ebariaux at Apr 17, 2012 10:25

Ok, in this case we still do need to add the panel hardware/os type as part of the REST call arguments, as I'd still like to be able to provide fixed designs separately for iPad and iPhone for example.

If that's the case, it would seem that controller could determine exactly one panel to return with the /rest/panels call, not sure the userSelectable attribute adds anything in this case?

If there's only a single matching design, is there any benefit in leaving the panel selection to the user, rather than skipping the step altogether?

Posted by juha at Apr 17, 2012 21:41
Document generated by Confluence on Jun 05, 2016 09:30