REST interface

[GoogleCodeExporter]

To simplify the integration of openHAB with other systems, it should offer a 
REST/HTTP-interface.

This interface should at least provide the following functionality:
- get the current state of an item
- send a command to an item
- query the item registry
- push bus events that the client has subscribed on
- get historical data of an item state (see issue 21)

The interface should be built on common web standards such as REST, JSON(P) etc.

Besides the integration-with-other-systems use case, this interface can then be 
used by openHAB UIs as well (like e.g. issue 24).

Original issue reported on code.google.com by xthirtyn...@gmail.com on 29 Mar 2011 at 2:18

[GoogleCodeExporter]

A good framework to use on the server side might be this: 
http://code.google.com/a/eclipselabs.org/p/restlet-integration-with-equinox/
It is also used for REST support in ECFs implementation of the OSGi RSA.

Original comment by xthirtyn...@gmail.com on 31 Mar 2011 at 8:48

[GoogleCodeExporter]

For very basic initial JSON support, the XStream lib might be useful as well:
http://xstream.codehaus.org/json-tutorial.html

Original comment by kai.openhab on 12 Apr 2011 at 5:44

[GoogleCodeExporter]

Some additional thoughts after Olivers comment on issue 24:

- Restlet was my first thought when looking for a REST framework
- Olivers point about Comet/Websocket support is very important: Server-push is 
a main feature for openHAB, which must be supported by the chosen framework, so 
Project Atmosphere is definitely worth a closer look.
- I have started a very first REST test with odata4j 
(http://code.google.com/p/odata4j/), but as this is very RDBMS-oriented I won't 
further follow this way, but rather directly use Jersey myself.
- Note: I was told about problems when using Jersey in an OSGi environment; so 
let's be prepared for possible hick-ups (although there should be OSGI-support 
with version 1.2 onwards).

Original comment by kai.openhab on 11 Jul 2011 at 8:40

[GoogleCodeExporter]

It's a bit of a pity that Jersey requires Java6 from version 1.3 onwards; so as 
long as we want to also support Java5, we are stuck with Jersey 1.2.

Original comment by kai.openhab on 12 Jul 2011 at 9:11

[GoogleCodeExporter]

I have just pushed a first REST API based on Jersey 1.2, see feature branch 
http://code.google.com/p/openhab/source/list?name=0.8.0-rest.

If you build the runtime from this branch, you can access the REST API entry 
page at http://localhost:8080/rest.
This will provide links to items and sitemaps, which are available at
http://localhost:8080/rest/items and http://localhost:8080/rest/sitemaps

Single items can be accessed at e.g. 
http://localhost:8080/rest/items/Temperature_FF_Bath and their plain value at 
http://localhost:8080/rest/items/Temperature_FF_Bath/state
Doing an HTTP PUT on the state url will post a status update, a HTTP PUT on the 
item url posts a command instead.

Besides complete sitemaps, you can also request single pages, e.g. 
http://localhost:8080/rest/sitemaps/demo/FF_Bath.

These functions should initially provide a good starting point to build dynamic 
UIs (such as HTML5/JS) on top. Still missing is the comet/polling support 
though, but this will be added later as well.

Looking forward to feedback!

Original comment by kai.openhab on 18 Jul 2011 at 4:14

• Added labels: Version-0.8.0
• Removed labels: Version-later

[GoogleCodeExporter]

Original comment by kai.openhab on 18 Jul 2011 at 4:14

• Changed state: Started

[GoogleCodeExporter]

Forgot to mention that the client can request either XML or JSON responses 
(using the Accepts-header).  JSONP will be easy to add as well. Only the state 
urls return a plain string and the HTTP PUT requests take plain strings as 
input.

For testing, I can recommend a HTTP REST client browser plugin like 
https://chrome.google.com/webstore/detail/ahdjpgllmllekelefacdedbjnjaplfjn.

Original comment by kai.openhab on 18 Jul 2011 at 7:45

[GoogleCodeExporter]

It works like a charm. I hooked up successfully my Arduino with Ethernet via 
the REST and the HTTP bindings for fully bidirectional REST interface. However 
there's one thing that miss me - a REST sensor input for items. 

For example now I hardcode in my Arduino the URI for an item state to send some 
data to openHAB. It looks like this: "/rest/items/Area1_Temperature/state". 
This works fine, but it's not a good approach. It's better to make the items to 
accept and understand REST in the items file, the way you do for every other 
interface (Serial, HTTP...)

Thanks for this another great feature! :)

Original comment by mishoboss on 20 Jul 2011 at 10:08

[GoogleCodeExporter]

Great to hear that it's working with your Arduino!

I am not sure if I fully understand your suggestion - do you mean we should 
make the REST API like a binding, so that you have to configure it for each 
item? What would be the advantage of that?

Original comment by kai.openhab on 20 Jul 2011 at 3:22

[GoogleCodeExporter]

FYI: I have merged the 0.8.0-rest branch to default, so the preliminary REST 
API is now available on the main 0.8.0 build.

Original comment by kai.openhab on 20 Jul 2011 at 3:23

[GoogleCodeExporter]

> do you mean we should make the REST API like a binding, so that you have to 
configure it for each item? What would be the advantage of that?

Yes and no. The REST URI "/rest/items/{item}/state" is a good standardized way 
to interact with UIs made for openHAB. However in my case I use the REST 
interface to interact with hardware, not an UI. In my case I made my hardware 
and I can put as URI, HTTP method and headers whatever I want. However if you 
want to interact with a stock hardware or Internet service, you have to play 
their game :) I imagine the REST binding as opposite to HTTP binding with an 
option to get data from the URI and/or the body of a PUT method for example.

Original comment by mishoboss on 20 Jul 2011 at 4:22

[GoogleCodeExporter]

I would prefer to keep the REST API REST-conform and not trying to be 
configurable to any kind of URI and HTTP headers... If there are systems that 
are not flexible enough to go through the REST API, there is still the 
possibility to do a polling through the HTTP in binding.

Original comment by kai.openhab on 21 Jul 2011 at 8:23

[GoogleCodeExporter]

The current version of the REST API is now documented on the wiki: 
http://code.google.com/p/openhab/wiki/REST

What is left to do is to add support for server push in order to be able to 
inform the client about item status changes and to send other notifications.

What could also be added (see issue 23) is read and write access to the config 
files - this would open the door for alternative configuration tools.

Original comment by kai.openhab on 17 Aug 2011 at 8:49

[GoogleCodeExporter]

> What could also be added (see  issue 23 ) is read and write access to the 
config files - this would open the door for alternative configuration tools.

This is a long waited feature by me. I would like to develop a user-friendly 
ExtJS based administration of openHAB. Thus I need well made services to access 
and modify every possible configuration item (items entries, rules entries, 
sitemap entries, transformation entries, images).

Original comment by mishoboss on 3 Sep 2011 at 8:05

[GoogleCodeExporter]

Hi Kai,
atmosphere is the perfect framework for comet and websocket support. Moreover 
atmosphere is able to broadcast messages e.g. via JGroups, JMS/ActiveMQ, Redis, 
XMPP. But atmosphere won't work with jersey 1.2. So kindly let me know if it's 
an option for you to quit the Java 5 support for this bundle. If so I can start 
to implement it.

Original comment by oliver.m...@gmail.com on 9 Sep 2011 at 2:59

[GoogleCodeExporter]

Hi Oliver,
dropping Java 5 support for the REST bundle more or less means dropping Java5 
support in general. I started off with Java6 anyhow, but then went down to 
Java5 to path the way for openHAB on embedded JVMs.
So it's a very difficult decision - either forget the idea of having openHAB on 
embedded systems or don't use atmosphere. Maybe it's worth putting this 
question to the discussion group to see if there is anybody with a strong 
opinion on that...

Original comment by xthirtyn...@gmail.com on 9 Sep 2011 at 3:08

[GoogleCodeExporter]

Ok, the general opinion in the dicussion group is that we can drop Java5 
support - so there are blocking reasons against upgrading Jersey anymore :-)

As this issue is about the initial REST API and marked for version 0.8.0 (for 
which it had been delivered), I am closing this issue now and opened the new 
issue 46 for the server-push support.

Original comment by kai.openhab on 17 Sep 2011 at 11:27

• Changed state: Implemented