Folders
Show
GET /folders/#{id}.format

Description

User can get folder information.
Authentication is required to use this method.


Arguments

  1. OAuth (mandatory): OAuth authentication params
  2. folder id (mandatory): folder identificator

Response example

Status:200

<folder>
        <id>2636</id>
        <name>FolderName</name>
        <date_creation>2010-10-18T12:08:58Z</date_creation>
        <parent_id>21</parent_id>
        <folders>
                <folder>
                        <id>138</id>
                        <name>SubFolder</name>
                        <date_creation>2010-10-20</date_creation>
                        <parent_id>2636</parent_id>
                        <folders/>
                        <devices/>
                </folder>
        </folders>
        <devices>
                <device>
                        <id>22</id>
                        <name>ComputerName</name>

                                ...

                </device>
                <device>
                        <id>23</id>
                        <name>ComputerName2</name>

                                ...

                </device>
        </devices>
</folder> 
Response values

  1. id: unique folder ID
  2. name: folder name
  3. date_creation: date and time when the folder was created
  4. parent_id: parent folder id
  5. folders: collection of folders that belong to this folder
  6. devices: collection of devices that belong to this folder

Error Codes

  1. 1100 - Folder id not found (404)


List All
GET /folders.format
GET /folders/#{id} /folders.format


Description

User can obtain a collection of folders of one account. Authentication is required to use this method.


Arguments

  1. OAuth (mandatory): OAuth authentication params
  2. parent_id (optional): you can specify a parent folder ID. You must specify the parent id using the second request type. If you don’t specify, the default value will be root.

Response example

Status: 200

<folders>
        <folder>

                …

        </folder>
        <folder>

                …

        </folder>
</folders>
Error Codes

  1. 1100 - Folder id not found (404)


Create
POST / folders.format
POST / folders/#{id} /folders.format


Description

The administrator can create a folder. Authentication is required to use this method.


Arguments

  1. OAuth (mandatory): OAuth authentication params
  2. name (mandatory): folder name
  3. parent_id (optional): folder parent ID
  4. folders (optional): collection of folders that belong to this folder
  5. devices (optional): collection of devices that belong to this folder

Request Body example

<folder>
        <name>UpdatedFolderName</name>
        <parent_id>12</parent_id>
        <folders>     
                <folder>
                        <id>12</id>  
                </folder>
        </folders>
        <devices>
                <device>
                        <id>26</id>  
                </device>
        </devices>

</folder>
Note: You can submit the parent_id in the URI using the second request type or as shown in the Request body example. If both methods are used at the same time the information submitted in the URI will have more priority. If you do not submit a parent-id, the folder is assigned to parent root. If you submit a devices or folder id that is already in other resource it will be updated automatically to the new resource. Response example

Status:201

Location: https://apifree.ntrglobal.com/folders/#{new-folder-id}
Error Codes

  1. 1100 - Folder id not found (404)
  2. 1101 - Folder name already in use in the level selected (403)
  3. 1000 - Device id not found (404)


Update
PUT /folders/#{id}.format
PUT /folders/#{id}/folders/#{id}.format


Description

User can update existing folder information. Authentication is required to use this method.


Arguments

  1. OAuth (mandatory): OAuth authentication params
  2. folder name (mandatory): you must specify folder name
  3. parent_id (optional): parent folder id
  4. folders (optional): collection of folders that belong to this folder
  5. devices (optional): collection of devices that belong to this folder

Request example

<folder>
        <name>UpdatedFolderName</name>
        <parent_id> 12</parent_id>
        </folders>
        <devices>
                <device>
                        <id>123458</id>
                </device>
        </devices>
</folder>
Note: You can submit the parent_id in the URI using the second request type or as shown in the Request body example. If both methods are used at the same time the information submitted in the URI will have more priority. If you do not submit any devices or folders, these items do not get unassigned from the folder. However, if you submit an empty devices or subfolders tag, all the devices/folders will be unassigned from the folder and assigned to unassigned/root. If you submit a collection of devices/folders, these items will be automatically assigned to the folder.
<folder>
        <id> 2636</id>
        <name>UpdatedFolderName</name>
        </devices>
</folder>
Response example

Status:200
Error Codes

  1. 1100 - Folder id not found (404)
  2. 1101 - Folder name already in use in the level selected (403)
  3. 1000 - Device id not found (404)


Destroy
DELETE / folders/#{id}.format

Description

User can remove a folder. Authentication is required to use this method.


Arguments

  1. OAuth (mandatory): OAuth authentication params
  2. folder id (mandatory): folder unique id

Response example

Status:200
Error Codes

  1. 1100 - Folder id not found (404)
  2. 1103 - Folder not empty (403)