Beehive 2.0 REST API documentation

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

New feature:

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

Index:

(1) Export a LIRC configuration as a text file, concatenate different RemoteSection.
(2) List all hardware vendors in the database
(3) List all models of a vendor in the database
(4) List all RemoteSections of a model in the database
(5) List all RemoteOptions of a RemoteSection in the database
(6) List all Codes of a Section in the database
(7) List all icons identified by button command name (Included in M2)
(8) List all icons (Included in M2)
(9) Get all templates from account (Included in M7)
(10) Save a template into account (Included in M7)
(11) Update a template into account (Included in M7)
(12) Delete a template from account (Included in M7)
(13) Upload template resource(images etc) into account (Included in M7)
(14) Download template resource(images etc) from account (Included in M7)
(15) Upload account resource(openremote.zip for controller) into account (Included in M7)
(16) Download account resource(openremote.zip for controller) from account (Included in M7)
(17) Search public templates by keywords from others (Included in M7)

(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.