Beehive 3.0 REST API documentation

The following document describes the Beehive 3.0 REST API which supports both XML and JSON.

By default the response format is XML, you can also use JSON. You needn't to specify 'Accept' type in HTTP header, if you want to use JSON, see how to 'Use JSONP format' in this document.

New feature:

• panel UI template save/query/delete
• openremote.zip upload/download
• WYSIWYG Testing

Index:

(1) Export a LIRC configuration as a text file, concatenate different RemoteSection.

• Request URL:

  /lirc.conf

• Request Method: GET

• Parameters: ids (RemoteSection ids, separate by comma)

• Sample Request Url:http://localhost:8080/beehive/rest/lirc.conf?ids=1,2

• Output:Combined Configuration files content as String.

• Sample Response:

  #
  # This config file has been automatically converted from a device file
  # found in the 06/26/00 release of the Windows Slink-e software
  # package.
  #
  # Many thanks to Colby Boles of Nirvis Systems Inc. for allowing us to
  # use these files.
  #
  # The original filename was: "3m mp8640 3m lcd projector.cde"
  #
  # The original description for this device was:
  #
  # 3m mp8640 3m lcd projector
  #
  
  
  
  begin remote
    name                    MP8640
    bits                    32
    flags                   SPACE_ENC
    eps                     20
    aeps                    200
  
    header                  8800 4400
    one                     550 1650
    zero                    550 550
    ptrail                  550
    repeat                  8800 2200
    gap                     38500
    toggle_bit              0
  
    frequency               38000
  
        begin codes
            STANDBY/ON              0x000000000AF5E817
            VOLUME'/\'              0x000000000AF548B7
            ...
  
        end codes
  
  end remote
  
  
  
  #
  # this config file was automatically generated
  # using lirc-0.6.6(serial) on Sat May 24 18:35:13 2003
  #
  # contributed by
  #
  # brand:                       Abit
  # model no. of remote control: ?
  # devices being controlled by this remote: AU10 audio card / windvd
  #
  
  
  begin remote
  
    name                    ABIT_WINDVD
    bits                    16
    flags                   SPACE_ENC|CONST_LENGTH
    eps                     30
    aeps                    100
  
    header                  9149 4422
    one                     666 1569
    zero                    666 474
    ptrail                  666
    pre_data_bits           16
    pre_data                0x807F
    gap                     108554
    toggle_bit              0
  
        begin codes
            OnOff                   0x000000000000E01F
            Mute                    0x00000000000010EF
            Title                   0x000000000000906F
            Screen                  0x00000000000050AF
            eject                   0x000000000000D02F
            ...
        end codes
  
  
  end remote
  
  

(2) List all hardware vendors in the database

• Request URL:

  /lirc

• Request Method: GET

• Sample Request Url:http://localhost:8080/beehive/rest/lirc

• Output:xml or json of a vendors list.

• Sample Response:
  • content-type:application/xml

    <vendors>
        <vendor>
            <id>1</id>
            <name>3m</name>
        </vendor>
        <vendor>
            <id>2</id>
            <name>abit</name>
       </vendor>
       ...
    </vendors>
    

  • content-type:application/json

    {"vendors":
          {vendor:
              [
                 {"id":1,
                  "name":"3m"
                 },
                 {"id":2,
                  "name":"abit"},
                 ...
               ]
           }
     }

• Errors:
  • Error Code:204, No Content. See HTTP/1.1 documentation.If system has no Vendor at all.

(3) List all models of a vendor in the database

• Request URL:

  /lirc/{vendor_name}

• Request Method: GET

• Sample Request Url:http://localhost:8080/beehive/rest/lirc/3m.
• Output:xml or json of a Model list of a Vendor.

• Sample Response:
  • content-type:application/xml:

    <models>
      <model>
        <id>1</id>
        <name>MP8640</name>
      </model>
    </models>
    

  • content-type:application/json :

    {"models":
             {model:
                   {
                     "id":1,
                     "name":"MP8640"}
             }
    } 

• Errors:
  • Error Code:404, Not Found. See HTTP/1.1 documentation. If system can't find such a Vendor .
  • Error Code:204, No Content. See HTTP/1.1 documentation. If this Vendor has no Model at all .

(4) List all RemoteSections of a model in the database

• Request URL:

  /lirc/{vendor_name}/{model_name}

• Request Method: GET

• Sample Request Url:http://localhost:8080/beehive/rest/lirc/3m/MP8640.
• Output:xml or json of a RemoteSection list of a Model.

• Sample Response:
  • content-type:application/xml:

    <sections>
       <section>
           <id>1</id>
           <comment>
    	    #
                # This config file has been automatically converted from a device file.
    	    #...
    	</comment>
    	<name>MP8640</name>
    	<raw>false</raw>
        </section>
    </sections>
    

  • content-type:application/json :

    {"sections":
        {section:
            {"id":1,
              "comment":"#\r\n# This config file has been automatically converted from a device file\r\n#...",
              "name":"MP8640",
              "raw":false
            }
        }
    }
    

• Errors:
  • Error Code:404, Not Found. See HTTP/1.1 documentation. If system can't find such a RemoteSection .

(5) List all RemoteOptions of a RemoteSection in the database

• Request URL:

   /lirc/{vendor_name}/{model_name}/{section_id}/options

• Request Method: GET

• Sample Request Url:http://localhost:8080/beehive/rest/lirc/3m/MP8640/1/options
• Output:xml or json of a RemoteOption list of a section.

• Sample Response:
  • content-type:application/xml:

    <options>
      <option>
         <id>1</id>
         <comment></comment>
         <name>name</name>
         <value>MP8640</value>
       </option>
      ...
    <options>
    

  • content-type:application/json :

    {"options":
             {option:
                    [
                      {"id":1,
                       "comment":"",
                       "name":"name",
                       "value":"MP8640"},
                       ...
                    ]
              }
    }
    

• Errors:
  • Error Code:204, No Content. See HTTP/1.1 documentation. If this RemoteSection has no RemoteOption at all .

(6) List all Codes of a Section in the database

• Request URL:

   /lirc/{vendor_name}/{model_name}/{section_id}/codes

• Request Method: GET

• Sample Request Url:http://localhost:8080/beehive/rest/lirc/3m/MP8640/1/codes
• Output:xml or json of a Code list of a RemoteSection.

• Sample Response:
  • content-type:application/xml:

    <codes>
      <code>
        <id>1</id>
        <comment></comment>
        <name>STANDBY/ON</name>
        <remoteName>MP8640</remoteName>
        <value>0x000000000AF5E817</value>
      </code>
      ...
    </codes>
    

  • content-type:application/json :

    {"codes":
           {code:
                  [
                      {"id":1,
                       "comment":"",
                       "name":"STANDBY\/ON",
                       "remoteName":"MP8640",
                       "value":"0x000000000AF5E817"
                       },
                       ...
                   ]
            }
    }
    

• Errors:
  • Error Code:204, No Content. See HTTP/1.1 documentation. If this RemoteSection has no Code at all .

(7) List all icons identified by button command name (Included in M2)

• Request URL:

   /icons/{icon_name}

• Request Method: GET

• Sample Request Url:http://localhost:8080/beehive/rest/icons/menu
• Output:xml or json of a Icon list of a button command name.

• Sample Response:
  • content-type:application/xml:

    <icons>
      <icon>
         <id>21</id>
         <fileName>http://localhost:8080/beehive/icons/menu.png</fileName>
         <name>menu</name>
      </icon>
      ...
    </icons>
    

  • content-type:application/json :

    {"icons":
            {icon:
                [
                  {"id":21,
                   "fileName":"http:\/\/localhost:8080\/beehive\/icons\/menu.png",
                   "name":"menu"},
                  ...
                ]
             }
    }
    

• Errors:
  • Error Code:404, Not Found. See HTTP/1.1 documentation. If system can't find any icons.
  • Error Code:204, No Content. See HTTP/1.1 documentation. If this button has no icons at all .

(8) List all icons (Included in M2)

• Request URL:

   /icons

• Request Method: GET

• Sample Request Url:http://localhost:8080/beehive/rest/icons
• Output:xml or json of a Icon list of all button command.

• Sample Response:
  • content-type:application/xml:

    <icons>
      <icon>
         <id>1</id>
         <fileName>http://localhost:8080/beehive/icons/power.png</fileName>
         <name>power</name>
      </icon>
      <icon>
         <id>2</id>
         <fileName>http://localhost:8080/beehive/icons/home.png</fileName>
         <name>home</name>
      </icon>
      ...
    </icons>
    

  • content-type:application/json :

    {"icons":
            {icon:
               [
                  {"id":1,
                   "fileName":"http:\/\/localhost:8080\/beehive\/icons\/power.png",
                   "name":"power"},
                   {"id":2,
                   "fileName":"http:\/\/localhost:8080\/beehive\/icons\/home.png",
                   "name":"home"},
                  ...
                ]
             }
    }
    

• Errors:
  • Error Code:404, Not Found. See HTTP/1.1 documentation. If system can't find any icons.
  • Error Code:204, No Content. See HTTP/1.1 documentation. If this button has no icons at all .

(9) Get all templates from account (Included in M7)

• Request URL:

   /account/{account_id}/templates/{share_scope}

• Request Method: GET
• Parameters: account_id(account id), share_scope(public, private)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/templates/public
• Output:xml or json of a template list in account.

• Sample Response:
  • content-type:application/xml:

    <templates>
    	<template>
    		<id>3</id>
    		<content>content...</content>
    		<keywords>sony,tv</keywords>
    		<name>t3</name>
    	</template>
            ...
    </templates>
    

  • content-type:application/json :

    {
        "templates":
          {template:
            [{
                "id":3,
                "content":"content...",
                "keywords":"sony,tv",
                "name":"t3"
            }
            ...
            ]
          }
    }
    

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:404, Not Found. See HTTP/1.1 documentation. If can't find any template.

(10) Save a template into account (Included in M7)

• Request URL:

   /account/{account_id}/template

• Request Method: POST
• Parameters: account_id(account id)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/template
• Output:xml or json of the new template in account.

• Sample Response:
  • content-type:application/xml:

    	<template>
    		<id>3</id>
    		<content>content...</content>
    		<keywords>sony,tv</keywords>
    		<name>t3</name>
    	</template>
    

  • content-type:application/json :

        {
            "template":
            {
                "id":3,
                "content":"content...",
                "keywords":"sony,tv",
                "name":"t3"
            }
    
        }
    
    

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:500, Server error. See HTTP/1.1 documentation.

(11) Update a template into account (Included in M7)

• Request URL:

   /account/{account_id}/template/{template_id}

• Request Method: PUT
• Parameters: account_id(account id), template_id (template id)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/template/1
• Output:xml or json of the updated template in account.

• Sample Response:
  • content-type:application/xml:

    	<template>
    		<id>3</id>
    		<content>content...</content>
    		<keywords>sony,tv</keywords>
    		<name>t3</name>
    	</template>
    

  • content-type:application/json :

        {
            "template":
            {
                "id":3,
                "content":"content...",
                "keywords":"sony,tv",
                "name":"t3"
            }
    
        }
    
    

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:500, Server error. See HTTP/1.1 documentation.

(12) Delete a template from account (Included in M7)

• Request URL:

   /account/{account_id}/template/{template_id}

• Request Method: DELETE
• Parameters: account_id(account id), template_id (template id)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/template/1
• Output: boolean result string.

• Sample Response:
  • if success :

    	true
    

  • if fail :

            false
    

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:500, Server error. See HTTP/1.1 documentation.

(13) Upload template resource(images etc) into account (Included in M7)

• Request URL:

   /account/{account_id}/template/{template_id}/resource

• Request Method: POST
• Parameters: account_id(account id), template_id (template id), zip file (in MultipartForm)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/template/1/resource
• Output: boolean result string.

• Sample Response:
  • if success :

    	true
    

  • if fail :

            false
    

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:500, Server error. See HTTP/1.1 documentation.

(14) Download template resource(images etc) from account (Included in M7)

• Request URL:

   /account/{account_id}/template/{template_id}/resource

• Request Method: GET
• Parameters: account_id(account id), template_id (template id)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/template/1/resource
• Accept-Type: application/zip
• Output: zip file stream.

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:404, openremote.zip not found. See HTTP/1.1 documentation.

(15) Upload account resource(openremote.zip for controller) into account (Included in M7)

• Request URL:

   /account/{account_id}/openremote.zip

• Request Method: POST
• Parameters: account_id(account id), template_id (template id), zip file (in MultipartForm)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/openremote.zip
• Output: boolean result string.

• Sample Response:
  • if success :

    	true
    

  • if fail :

            false
    

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:500, Server error. See HTTP/1.1 documentation.

(16) Download account resource(openremote.zip for controller) from account (Included in M7)

• Request URL:

   /user/{username}/openremote.zip

• Request Method: GET
• Parameters: username(username of account)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/account/1/openremote.zip
• Accept-Type: application/zip
• Output: zip file stream.

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:404, openremote.zip not found. See HTTP/1.1 documentation.

(17) Search public templates by keywords from others (Included in M7)

• Request URL:

   /templates/keywords/{keywords}/page/{page}

• Request Method: GET
• Parameters: keywords(keywords for search), page(page number)
• HTTP basic header Authorization : "Basic base64(username:md5(password,username))"
• Sample Request Url:http://localhost:8080/beehive/rest/templates/keywords/sony,tv/page/1
• Output:xml or json of a template list by keywords.

• Sample Response:
  • content-type:application/xml:

    <templates>
    	<template>
    		<id>3</id>
    		<content>content...</content>
    		<keywords>sony,tv</keywords>
    		<name>t3</name>
    	</template>
            ...
    </templates>
    

  • content-type:application/json :

    {
        "templates":
         {template:
           [{
                "id":3,
                "content":"content...",
                "keywords":"sony,tv",
                "name":"t3"
            }
            ...
            ]
         }
    }
    

• Errors:
  • Error Code:401, unauthorized. See HTTP/1.1 documentation.
  • Error Code:404, Not Found. See HTTP/1.1 documentation. If can't find any template.

(18) WYSIWYG testing, show available panel list (Included in M7)

• Request URL:

   /user/{username}/rest/panels

• Request Method: GET
• Parameters: username
• HTTP basic header Authorization : "Basic base64(username:password)"
• Sample Request Url:http://localhost:8080/beehive/rest/user/dancong/rest/panels
• Output:xml of a panel list.

• Sample Response:

  <openremote>
  	<panel id="xxx" name="iphone 1" />
          ...
  </openremote>
  

• Errors:
  • Error Code:426, panel.xml not found.
  • Error Code:427, Invalid panel.xml.

(19) WYSIWYG testing, show panel UI content by panel name (Included in M7)

• Request URL:

   /user/{username}/rest/panel/{panel_name}

• Request Method: GET
• Parameters: username, panel_name (panel name)
• HTTP basic header Authorization : "Basic base64(username:password)"
• Sample Request Url:http://localhost:8080/beehive/rest/user/dancong/rest/panel/iphone%201
• Output:xml of panel UI content.

• Sample Response:

  <openremote xmlns="http://www.openremote.org" xmlns:xsi="htt//www.w3.org/2001/XMLSchema-instance" xmlns:schemaLocation="htt//www.openremote.org panel.xsd">
    <screens>
      <screen id="3" name="Starting Screen" inverseScreenId="5">
        <background fillScreen="true">
          <image src="background1270803578135.png" />
        </background>
        <absolute left="17" top="63" width="150" height="50">
          <label id="44" fontSize="14" color="#000000" text="Donna's home" />
        </absolute>
        <grid left="5" top="103" width="200" height="200" rows="4" cols="4">
          <cell x="2" y="0" rowspan="1" colspan="2">
            <button id="19" name="Login">
              <navigate to="login" />
            </button>
          </cell>
          <cell x="2" y="1" rowspan="1" colspan="2">
            <switch id="29" />
          </cell>
        </grid>
      </screen>
      <screen id="5" name="Starting Screen" landscape="true" inverseScreenId="3">
        <background relative="CENTER">
          <image src="Picture11270819622002.png" />
        </background>
      </screen>
      <screen id="30" name="s2">
        <background fillScreen="true">
          <image src="1270799825satellite1270809371836.png" />
        </background>
        <absolute left="82" top="336" width="224" height="52">
          <button id="37" name="Button" />
        </absolute>
        <grid left="4" top="112" width="300" height="200" rows="4" cols="4">
          <cell x="2" y="0" rowspan="1" colspan="2">
            <button id="33" name="Button" />
          </cell>
          <cell x="1" y="1" rowspan="2" colspan="1">
            <switch id="35" />
          </cell>
          <cell x="0" y="3" rowspan="1" colspan="3">
            <slider id="39" passive="true" vertical="false" />
          </cell>
        </grid>
      </screen>
      <screen id="41" name="s1">
        <absolute left="67" top="183" width="150" height="50">
          <label id="46" fontSize="14" color="#FFFFFF" text="group2 screen1" />
        </absolute>
      </screen>
    </screens>
    <groups>
      <group id="2" name="Default Group">
        <tabbar>
          <item name="to g2">
            <navigate toGroup="40" />
          </item>
          <item name="setting">
            <navigate to="setting" />
            <image src="19gear1270809419929.png" />
          </item>
          <item name="p">
            <navigate to="previousScreen" />
          </item>
          <item name="n">
            <navigate to="nextScreen" />
          </item>
          <item name="back" />
        </tabbar>
        <include type="screen" ref="3" />
        <include type="screen" ref="5" />
        <include type="screen" ref="30" />
      </group>
      <group id="40" name="g2">
        <tabbar>
          <item name="to g1">
            <navigate toGroup="2" />
          </item>
          <item name="back">
            <navigate to="back" />
          </item>
        </tabbar>
        <include type="screen" ref="41" />
      </group>
    </groups>
  </openremote>
  

• Errors:
  • Error Code:426, panel.xml not found.
  • Error Code:427, Invalid panel.xml.
  • Error Code:428, panel name not found.

Use JSONP format

JSON-P is a method of wrapping the JSON output of API calls to allow other developers to call cross site. To use JSON-P, developer should include a 'callback' as request parameter like this: http://localhost:8080/beehive/rest/lirc?callback=aaa
then response will be :

aaa && aaa({"vendors":{vendor:[{"id":1,"name":"3m"},{"id":2,"name":"abit"}]}})